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

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-07-24 13:38:45

At 07:24 PM 7/23/2001, Jeff Garland wrote:
 >> 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 guess we differ about what documentation is.  When I look at
http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-doxygen-3.0/index.html, I 
don't see a "Reference Guide" to the standard library.  Instead I see 
synoptic listings and graphics.  No hint as to semantics.  No distinction 
between interface components and implementation components.  No overviews, 
no requirements, no concepts. No preconditions, effects, throws, returns, 
notes, rationale, or postconditions.  Am I missing something?  This looks 
like useful auxiliary documenation for a particular implementation, to go 
with the primary documentation, if you had any.  But it just doesn't look 
like the primary documentation to me.

Continuing with the C++ Standard Library as the example, The C++ standard 
document itself is what I think of reference documentation, as is the 
Dinkumware standard library reference (see 
http://www.dinkumware.com/refxcpp.html).

A book like Nico Josuttis, "The C++ Standard Library", is another example 
of what I would think of as documentation for the standard library, this 
time more tutorial and user oriented, and somewhat less reference oriented.

I'll feel better about Doxygen when someone shows me an example that 
actually looks like what I think of as primary documentation.

--Beman