Re: [boost] Reference documentation: one approach

From: Ken Shaw (ken_at_[hidden])
Date: 2002-10-29 15:47:04

----- Original Message -----
From: "Jeff Garland" <jeff_at_[hidden]>
To: "Boost mailing list" <boost_at_[hidden]>
Sent: Tuesday, October 29, 2002 1:52 PM
Subject: RE: [boost] Reference documentation: one approach

>
> > > Doxygen is great for documenting interfaces.  It does not help with
> > > any other documentation as far as I can tell.
> >
> > While doxygen is mostly used for documenting interfaces it can be used
for
> > kinds of documentation as well.
>
> My advice on Doxygen with respect to boost is: don't waste your time.  I
> know from discussing this for too long here that there are too many boost
> developers that don't like Doxygen, for a variety of reasons, for it
> to fly in boost-land.  The primary issue is typically the 'accuracy'
> associated with a tool that doesn't use a full C++ parser and problems
> with heavy template usage.
>
> > You can include any sort of text at most any level of the documentation.
Our
> > internal XML library is extensively documented including how-to's,
examples,
> > known bugs, feature wish lists and to-do lists at the library, file, and
> > class levels, all of which is generated by doxygen.
> >
> > I would be happy to doxygenize a smallish Boost project to demonstrate.
>
> No need.  I use it as a supplement for the date_time library, and have
> been criticized for depending on it too much.  One problem is that the
> resulting documentation is really too large to include as part
> of the boost release meaning that users either have to look online or
> generate it locally.
>
>
http://www.crystalclearsoftware.com/libraries/gdtl/gdtl_ref_guide/index.html
>

A very nice example of the sort of HTML docs doxygen can generate. I really
don't see why anyone would have a problem with that. It should also be noted
that doxygen can produce LaTex and several other formats besides HTML.

> Anyway regardless of the technology there is a big difference in
> using a documentation generator or literate programming environment
> than shifting the standard documentation form to XML/Docbook.
> I think XML/Docbook might be able to get some consensus, but I
> doubt we are going to get agreement on the other.  I see Doc-Book
> and other XML solutions as an evolutionary step up from the
> HTML documentation because it clearly separates content from
> format and makes automated processing for different uses and
> forms much easier.
>

Is there a DocBook application that scans source code? One of the big
advantages of doxygen ( and JavaDocs ) is that relatively understandable
comment blocks precede the functions to be documented. This has the
advantage that the process of generating docs also comments the source and
header files.

Ken Shaw