Re: "Documentation by paper"

[kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)]

  /**
   *  @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.

This *exactly* the sort of clutter I'm very strongly against.  It makes it
*far* harder to read the source file with those "@param" tokens in the way.
And the "*" in each line is a violation of the GNU coding conventions, in
addition to adding yet more clutter.  Sure, external documentation can be
handy, but not at that huge readability cost.

This should simply be:

/* This function searches a sequence for a matching sub-sequence.
   FIRST1, LAST1, FIRST2 and LAST2 are allforward 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.