Re: "Documentation by paper"

[law at redhat dot com]

In message <10401271850.AA29985@vlsi1.ultra.nyu.edu>, Richard Kenner writes:
 >  /**
 >   *  @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.
And totally useless unless one goes into the source code to read it.

IMHO that's actually a huge long term liability as it actually discourages
writing good API interfaces and documenting them, while at the same time
encourages developers to actually look at the implementation to determine
if the code in question actually does what they want.

Now having said that, I've never liked reading doxygen annotated comments;
I find the annotations make the comments harder to read.  Unfortunately, I
don't have a better solution.




jeff