Re: [PATCH] Doxygen documentation for slist

[Jonathan Wakely <cow at compsoc dot man dot ac dot uk>]

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