Doxygen - another sample, preliminary comments

[Rich Churcher]

I'm still looking at Doxygen - so far, it's quite encouraging stuff.
I've placed the results of a preliminary run on the web, temporarily:

  http://www.snurse-l.org/c++/libstdc++-v3/

This is what happens when you sic Doxygen on the current CVS build
with a simple configuration and one file "Doxygenised".  The graphical
class hierarchy page is somewhat reduced, since it was a bit large for
a single download, but I've left in some of the more interesting
graphs.  It still takes awhile to load, so be warned.

  http://www.snurse-l.org/c++/libstdc++-v3/inherits.html

Since we were already using <vector> as an example, I've played with
adding information to stl_vector.h - both inline, and using an
external file.  The file `vector.doc' is attached, as a simple example
of separating the documentation from the source file.  This was placed
in a separate subdirectory off $prefix/include/g++-v3, and Doxygen did
the rest.

Good points so far:

  * fast, stable
  * generates various formats seamlessly, no conversion hassles
  * don't necessarily have to clutter source with long comments
  * graphing facility is excellent, and completely automatic
  * I like the way you can move between source listings and 
    documentation easily - everything is cross-linked

The initial set-up and configuration would take awhile, once we
decided on how everything was to look, but long-term maintenance and
upkeep should be fairly simple.

-- 
Cheers,
Rich.