This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: "Documentation by paper"


I'm going to regret getting into this discussion...


On Tue, Jan 27, 2004 at 12:12:22PM -0700, law@redhat.com wrote:
> 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.

Do you have a suggested syntax which allows us to extract nicely formatted
HTML, LaTeX, and troff documentation?


>  >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.

Blame the leading '*' on me.  I introduced doxygen into libstdc++, and
all these comments have followed that initial style.


>  >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.

Exactly.  The @param and @return and whatnot are not intended for humans
until after they've been processed.  If you think variables look good in
all caps in the source, fine, that's a valid opinion, but they look like
crap in HTML and LaTeX output.

I have complaints about doxygen myself.  But IMO it's better than anything
else that's been concretely suggested.  And -- undisputed fact -- it's
better than what we habe right now, which is nothing.

-- 
Besides a mathematical inclination, an exceptionally good mastery of
one's native tongue is the most vital asset of a competent programmer.
                                          - Edsger Dijkstra, 1930-2002


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]