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


Thanks for the detailed response.

I'd agree that the fact that STL collections don't manage pointers is
so basic that the user is in trouble if he doesn't understand that.  I
can see how replicating that information feels dubious.

I guess it was the information about iterator invalidation that has
taken a bit longer to seep through my brain.  I'm always nervous that
deleting from a map might invalidate an adjacent iterator, for
example.  Thankfully, SGI's online documentation
http://www.sgi.com/tech/stl/ makes this clear (in the documentation of
each container).

I never imagined replicating any of this information per function. 
Once per file would be best IMO.

   -Ken

On Thu, 27 Jan 2005 15:26:33 +0000, Jonathan Wakely
<cow@compsoc.man.ac.uk> wrote:
> On Thu, Jan 27, 2005 at 07:10:19AM -0800, Kenneth Duda wrote:
> 
> > > > > > +       *  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.
> 
> First, thanks for the feedback. These docs are meant for users, not
> the implementors, so IMHO your opinion counts.
> 
> 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.
> 
> The fact that the standard containers don't manage pointers _is_
> introductory material, and so IMHO that's precisely the place it should
> be documented.
> 
> Maybe I'm too biased, because I can't understand why anyone would ever
> think the pointer would be deleted here:
> 
>    int* p = new int(0);
>    int i(0);
>    std::vector<int*> v;
>    v.push_back(p);
>    v.push_back(&i);
> 
> How is the vector supposed to know to delete p, but not &i ?
> 
> I would have no objection to moving the comment to the head of the file,
> so it's said once per container (and including your suggestion of ("as
> with all STL containers") but on every function just seems pointless.
> 
> jon
> 
> --
> "The future is here. It's just not evenly distributed yet."
>        - William Gibson
>


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