This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
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