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
> > 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.
> > internal XML library is extensively documented including how-to's,
> > 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.
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
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk