Re: [PATCH] Doxygen documentation for slist

[Lorenz Minder <lminder at gmx dot net>]

Hi,

Jonathan Wakely wrote:
> > I'm not an experienced writer for technical documentation, nor is
> > english my mother tongue, so comments and improvements are highly
> > welcome.
> 
> I've made a few suggestions below, I hope they're useful.

Thanks! I've applied your changes in my local copy. Comments below.

> > +      /**
> > +       *  @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?

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

I will send an updated patch for slist in a day or so, so I can reread
myself again, and others can comment if they wish to do so.

--Lorenz