RE: libstdc++ Documentation

[Greg Bumgardner <bumgard at roguewave dot com>]

I'm afraid I'm one of those people who dropped the ball on the doxygen
stuff. I've been pretty busy tracking down some bugs in doxygen that arise
when processing my own code, and have not yet attempted to make any V3
patches to support doxygen use.

I do find that doxygen does a great job of documenting C++ libraries, and
would argue that generating documentation for libraries is its primary
function. It occasionally has some problems with templates, but most of
these problems seem to have been fixed in the most recent releases.  As for
handling generated/configured code, I normally run doxygen after I configure
and build a library, so doxygen doesn't need to know anything about
configuration-specific files.  This may not be appropriate for generating
cross-configuration design documentation, but should provide satisfactory
end-user documentation.

I agree that it will likely be somewhat difficult retrofitting the current
V3 code base to support doxygen-based code generation. It's not to difficult
to get good results when you code for doxygen from the very beginning, but
it is probably quite a bit more work doing it after-the-fact. 

As for embedding documentation, I also agree that this is a monumental task.
If such an attempt were made, the docs should probably just be lifted from
the standard (I don't recall seeing a copyright on the standard itself).

-g.b.

> -----Original Message-----
> From: Victor Kirk [mailto:vic.kirk@btinternet.com]
> Sent: Wednesday, March 14, 2001 1:06 PM
> To: libstdc++@gcc.gnu.org
> Subject: Re: libstdc++ Documentation
> 
> 
> Hi,
> 
> Please excuse my long reply, it won't happen again.
> 
> At 09:57 PM 3/13/01 -0500, Phil Edwards wrote:
> 
> >... it would be 1) freakishly big and tiring, 
> I realise how much work would be involved and that it would be a 
> duplication of effort. However I beleive that availability of accurate
> and concise information would be a great compliment to libstdc++ and 
> encourage it's use.
> 
> >and 2) redundant,
> Yes it would be redundant in the sense that the information is 
> available from other sources.  However as far as I am aware there 
> is very little available under a GNU license, which I think is an
> important thing.  (I am ignoring the the C++ Programming How-To).
> 
> Besides, I spend the majority of my development behind a firewall and
> don't want to buy two copies of each book I own.
> 
> I have a vested interest in anything that promotes the use of C++, I 
> enjoy the using the language (I switched from being a scientist to 
> a software engineer after discovering C++). I enjoy being able to 
> use GNU software, so helping people to develop more software benefits
> me again.
> 
> I would also get something personaly from such a task, not least
> of which would be a much better understanding of the Standard library.
> It would also be a way for me to contribute to libstdc++ in a way I
> feel that I am technicaly capable.
> 
> Based on direct experience and discussions other software 
> engineers from
> other companies I have observed that C++ is seen as having a large
> interlectual overhead, particularly templates and the 
> library. Over the 
> period since standardisation I have inspected and moderated a fair 
> amount of other peoples C++ code, during this time I can report that I
> have seen very little usage of the library and that which I have seen
> rarely goes beyong using std::vectors or std::list (Ive seen 
> a few 'sort's 
> a few times and once saw an 'accumulate').
> 
> This is not just the company I work for, but our partner companies and
> the numorus contract staff that have passed through.
> 
> Companies I have been interviewed by have actually said that they 
> dont use the STL because their developers dont understand it. I 
> seriously doubt that their developers are incapable of understanding.
> 
> Lastly, as a user I would tend to go for a library that is easy to 
> use and understand.
> 
> >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....
> 
> >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.
> 
> I've had my email address for nearly three years and intend to 
> continue using it.
> 
> At 08:43 AM 3/14/01 -0500, Stephen M. Webb wrote:
> >I have a Doxyfile (the Doxygen config file) I use to 
> generate html and
> >man pages of the public interfaces to the library, just for quick
> >lookups.  The problem is not the config file (takes 5  minutes to set
> >one up the right way) but rather the fact the libstdc++ is a library
> >(forgive the obvious), and Doxygen is designed for an end 
> product.  It
> >has difficulty coping with things like generated source and
> >multiplatform source (the whole header file thing drives it mad) and
> >its support for templates is limited -- not an asset with a template
> >library.
> I agree with this, I breifly ran doxygen on the files yesterday and
> can say the results where far from staisfactory (this was not 
> using the
> config file provided by Stephen).  Although I'm sure it could 
> be improved 
> upon.
> 
> I am personnaly a big fan of doxygen (and javadoc), I am not sure
> that it would not be the best tool for the job. I feel strengths 
> lie on projects that dont (strictly) follow a design or specification,
> and of course where design does not formally exist.
> 
> For something that follows an external specification I dont feel that 
> there is much to be gained from having documentation embedded 
> within the 
> code, and would just add noise to the content and change log.
> 
> I think I would prefer to use Docbook and modualarise the files to
> make it easier for others to contribute.
> 
> 
> Regards,
> 
> Vic
>