Re: "Documentation by paper"

[Joe Buck <Joe dot Buck at synopsys dot COM>]

On Tue, Jan 27, 2004 at 01:01:32PM -0500, Richard Kenner wrote:
>     Paper documentation is nice as well, but the way to get both, and to
>     keep the code and documentation consistent, is to use doxygen-style
>     comments and use that to generate the documentation.
> 
> Agreed.  I have no problems with having a *second* copy, as long as the
> primary one is in the file and "doxygen-style" does't clutter up the
> source and make it harder to read the comments.

> I don't know anything about the annotations, but if it were a tradeoff
> between making the source slightly less clean to get a secondary documention,
> I'd vote *against* the secondary documention since it isn't nearly as
> useful as a easy-to-read documentation in the source.

Here is an example of a doxygen comment that describes a function.
It describes one of the std::search functions in the standard C++ library.

See

http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespacestd.html#a287

for the output.

The directives @p and @c just make the output prettier and aren't strictly
necessary, and in fact it appears that they are misused here: @p or @c
seem to set the next identifier in a fixed-width font, but they seem to
do nothing if the next token is not an identifier.

  /**
   *  @brief Search a sequence for a matching sub-sequence.
   *  @param  first1  A forward iterator.
   *  @param  last1   A forward iterator.
   *  @param  first2  A forward iterator.
   *  @param  last2   A forward iterator.
   *  @return   The first iterator @c i in the range
   *  @p [first1,last1-(last2-first2)) such that @c *(i+N) == @p *(first2+N)
   *  for each @c N in the range @p [0,last2-first2), or @p last1 if no
   *  such iterator exists.
   *
   *  Searches the range @p [first1,last1) for a sub-sequence that compares
   *  equal value-by-value with the sequence given by @p [first2,last2) and
   *  returns an iterator to the first element of the sub-sequence, or
   *  @p last1 if the sub-sequence is not found.
   *
   *  Because the sub-sequence must lie completely within the range
   *  @p [first1,last1) it must start at a position less than
   *  @p last1-(last2-first2) where @p last2-first2 is the length of the
   *  sub-sequence.
   *  This means that the returned iterator @c i will be in the range
   *  @p [first1,last1-(last2-first2))
  */