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

From: Jeff Garland (jeff_at_[hidden])
Date: 2001-07-24 14:44:47

Beman wrote:
> -----Original Message-----
> 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

I seriously doubt it :-)

> 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.

I absolutely agree, the work hasn't been done to document the library.  To get
really useful reference documentation using Doxygen, work must be done to
document all the items you mention. However, since the "structural" elements are
derived by the generator, instead of writing them over in a standalone document,
maintenance is easier.

> 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).

I would also call this reference documentation.

> 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.

Also agreed.  This book would be what I call "User guide" documentation (BTW, I
think my terminology comes from the way Rogue Wave has traditionally broken down
library documentation).  It has some reference type elements, but really it
provides summary and tutorial information.

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

I have some, unfortunately it is proprietary. What I have done for proprietary
work is use doxygen generated information for the reference guide and layered on
user guide documentation (primarily authored in HTML so it can have links to the
reference documentation) on top.  At the moment, this requires a good bit of
"duct tape" to patch things together so I can get a unified web site and PDF
docs at the end.

Jeff