Re: [PATCH] Doxygen documentation for slist

[Phil Edwards <phil at codesourcery dot com>]

Thanks for the cc, Jonathan.  I'm still catching up on list mail from
2004, sadly...


On Thu, Jan 27, 2005 at 09:32:22AM +0000, Jonathan Wakely wrote:
> On Thu, Jan 27, 2005 at 01:25:21AM +0100, Lorenz Minder wrote:
> 
> > > > +      /**
> > > > +       *  @brief  The default constructor creates an empty slist.
> > >                                                               ^ %slist
> > 
> > I've applied this change for now, although I'm not too sure about it:
> > slist won't be automatically linked anyways (since there is no
> > slist::slist type/namespace), and I think it would be better to actually
> > remove the % before every "slist" instead.  I think it's better to use %
> > sparingly, if possible. What do you guys think?
> 
> If it's not needed to prevent a link being created then I'd tend to
> agree with you. Phil?

"As sparingly as possible" is a good rule to follow with the % suppressor.
At first I had to use it everywhere; a later version of Doxygen made many
of those occurrances unneeded and we took them out.


> My objection is that the Doxygen docs will probably never be a full
> user guide to the stdlib, they will be an API reference when you want to
> quickly look up the signature of a function, or the parameters for a
> template.  For those uses, having the same warning repeated on every
> function just gets in the way.

I agree.

If you want a common block of text to be on every {page, group, container,
etc}, you might consider sticking the text in doxygroups.cc.  That allows you
to keep the clutter out of the header files, and avoids duplication as well.


Phil

-- 
Behind everything some further thing is found, forever; thus the tree behind
the bird, stone beneath soil, the sun behind Urth.  Behind our efforts, let
there be found our efforts.
              - Ascian saying, as related by Loyal to the Group of Seventeen