Re: libstdc++ Documentation

[Phil Edwards <pedwards at disaster dot jaj dot com>]

On Tue, Mar 13, 2001 at 02:16:16AM +0000, Victor Kirk wrote:
> >http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html
> 
> I did see these documents but it wasnt quite what I was 
> meaning. 
[...]
> look.  I assume we are talking about documenting the atcual 
> use of the library, rather than developers info?  I would be 
> inclined to work through alphabeticaly unless anyone has any
> strong preferences.

Sounds like you're planning to write a complete reference/tutorial for
users?  I've been shying away from this, for two reasons:  it would be 1)
freakishly big and tiring, and 2) redundant, as there are a couple of very
good references and tutorials already published (the STL one by Austern
comes to mind, also the one covering the entire library by Josuttis).
Those books run to hundreds of pages.  They have to, in order to be complete
and useful.  I don't think you want to write that much.  :-)

May I suggest alternatives?

The stuff under documentation.html above are also user-level reference
and tutorial notes, but they assume that you know the signatues already,
or have something like a Josuttis reference handy if you're a beginner.
Those pages don't document simple straight usage; they document common
idioms and FAcodingQs and useful techniques; things usually not found
in bog-standard C++ library references.  Any contributions to those are
most welcome.

Many people have thrown around the ideas of documentation for other library
developers.  Right now there is zero of that, although maybe that wasn't
what you had in mind.

The doxygen bits would go a long long way towards all of the above.
Maybe I oughta slip some of my other stuff a week and read up on doxygen.cfg
instead....


Phil
It's disturbing that the people who volunteer for doxygen stuff vanish
shortly thereafter.  I don't just mean "off the mailing list," I mean
*gone*, like email to them bounces with "no such user".  Some weird Curse
of the Doxy snatches them in their sleep or something.

-- 
pedwards at disaster dot jaj dot com  |  pme at sources dot redhat dot com
devphil at several other less interesting addresses in various dot domains
The gods do not protect fools.  Fools are protected by more capable fools.