RE: [boost] Re: Review: Boost Coding Guidelines

From: Jeff Garland (jeff_at_[hidden])
Date: 2001-07-23 18:24:01

Beman wrote:

>  >I'm currious, whats wrong with a tool such as doxygen?
>  >http://www.stack.nl/~dimitri/doxygen/

Not to rehash old ground too much, (search the archive for previous "discussion"
of this topic), but some of us (well, at least me:-) like doxygen just fine.  I
won't cover the "why Doxygen won't work for boost" topic again.

> DocBook and Doxygen are really two different animals.

Agreed. DocBook is a "schema" and Doxygen is a documentation format (at least
partially derived from JAVA doc) and extraction tool.  IMO, DocBook is better
suited for publishing, that is "User Guide" type documentation, while Doxygen's
strength is really "Reference Guide" documentation.

I do disagree with the heavy-duty, light-duty characterization....see below.

> DocBook is a heavy-duty solution, with a whole tools industry behind it
> (because it is XML based).  It can solve difficult documentation problems

AFAIK the "tools industry" behind doc book has not produced anything that can
analyze C++ code and produce DocBook elements for use in reference
documentation.  If there is such a tool please point me there.....

> like generating output based on multiple user-specified styles and design
> formats, all from the same source, and directed to a wide range of physical
> output formats.

Doxygen supports lots of backend formats from the same source as well.

> Able to handle large volumes (I think some uses run into tens of thousands of
pages.)

A large system documented with Doxygen can generate thousands of
cross-referenced web pages and graphics.  I don't think this proves anything.
See the documentation of the ACE/TAO library for an example of large scale
library documentation using Doxygen.

 http://doc.ece.uci.edu/Doxygen/Stable/

>One downside is there is a considerable up front learning curve.

As there is to get good results with Doxygen as well.

> Doxygen is a light-duty solution, with almost no tool support other than
> the generator itself.  It is, however, easy to get going with.  OTOH, most
> of the results I've seen give only a brief illusion of documentation rather
> than the real thing.

The "illusion" is created by running Doxygen on "undocumented code".  Obviously
the benefits of a documentation tool cannot be fully understood until someone
actually documents the code.   That is, you will never get coherent
documentation from code without actually writing documentation.  OTOH, you can
generate reference material that is useful even without annotated documentation.
The GCC library team has started using Doxygen, so it will be interesting to see
how this progresses....

http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-doxygen-3.0/index.html

> There are also some Literate Programming tools available that fall
> somewhere between DocBook and Doxygen.  I'm not really familiar with their
> pros and cons.

Nor am I....

Jeff