Boost logo

Boost :

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk