Re: "Documentation by paper"

[Phil Edwards <phil at codesourcery dot com>]

On Tue, Jan 27, 2004 at 11:43:39AM -0800, Joe Buck wrote:
> On Tue, Jan 27, 2004 at 01:50:36PM -0500, Richard Kenner wrote:
> > This should simply be:
> > 
> > /* This function searches a sequence for a matching sub-sequence.
> >    FIRST1, LAST1, FIRST2 and LAST2 are all forward iterators.
> >    The first iterator J in the range [FIRST1,LAST1-(LAST2-FIRST2)) such that
> >    *(J+N) == *(FIRST2+N) for each @c N in the range [0,LAST2-FIRST2) is
> >    returned, or LAST1 if no such iterator exists.  */
> > 
> > That's a *lot* cleaner and easier to read.
> 
> Fine, doxygen is cool with that.  If you write it as
> 
> /** This function searches a sequence for a matching sub-sequence.
>     FIRST1, LAST1, FIRST2 and LAST2 are all forward iterators.
>     The first iterator J in the range [FIRST1,LAST1-(LAST2-FIRST2)) such that
>     *(J+N) == *(FIRST2+N) for each @c N in the range [0,LAST2-FIRST2) is
>     returned, or LAST1 if no such iterator exists.  */
> 
> it will be treated as a doxygen comment, with the first sentence as
> the brief description and the whole paragraph as the long description.
> All I changed was the extra * character.

Now look at the output.  Compare it to what the output looked like before.
Note the loss of presented information.