This is the mail archive of the
mailing list for the GCC project.
Re: "Documentation by paper"
- From: law at redhat dot com
- To: kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)
- Cc: Joe dot Buck at synopsys dot com, gcc at gcc dot gnu dot org
- Date: Tue, 27 Jan 2004 12:12:22 -0700
- Subject: Re: "Documentation by paper"
- Reply-to: 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.