RE: [boost] Reference documentation: one approach

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-10-29 14:52:18

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

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.

One interesting problem in Doug's XML example is the line:

  template<typename Signature1, typename Allocator1, typename Signature2, typename Allocator2> void operator!=(const
function<Signature1, Allocator1>&, const function<Signature2, Allocator2>&);

is way too long.  Since the current rendering doesn't ever wrap,
this is rather difficult to read.  It is unlikely a human would
choose this formatting and it might be very difficult to control
with XSLT.

Jeff