This is the mail archive of the libstdc++@gcc.gnu.org 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


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?

> > > +       *  It only invalidates iterators/references to the element being
> > > +       *  removed.  The user is also cautioned that this function only
> > > +       *  erases the elements, and that if the elements themselves are
> > > +       *  pointers, the pointed-to memory is not touched in any way.
> > > +       *  Managing the pointer is the user's responsibilty.
> > 
> > This is true of all containers, does it need to be said?
> 
> Agreed, it can be removed. This was already in the documentation for
> list, so I adopted it originally, even though I find it myself a bit
> cumbersome. I will probably send another patch removing the
> corresponding lines in std::list as well, together with corrections of
> some mistakes I found in the docs for std::list while reading them.

Ah, I didn't realise it was taken from std:list, sorry. What do others
think about repeating that info for every function of every container?
Would it be better to say it once-and-once-only, in the FAQ or the main
documentation? (Jerry, I think you added that text originally.)

jon

-- 
"He who knows does not speak.
 He who speaks does not know."
	- Lao Tze


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