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

> > > > +       *  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

As a random user of the standard library, I'd like to vote all zero of
my votes for having this information in the documentation for each
container, possibly prefixed with "As with all STL containers, ...".  
The reason is that when I'm looking for this sort of information, I'm
much more likely to check the documentation for the container I'm
currently wrestling with than I am to read through some sort of
introductory material.

Thanks for listening,


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