This is the mail archive of the mailing list for the libstdc++ 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: [PATCH] Doxygen documentation for slist

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  That allows you
to keep the clutter out of the header files, and avoids duplication as well.


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

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