Re: libstdc++ Documentation

[Victor Kirk <vic dot kirk at btinternet dot com>]

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