Re: [boost] Reference documentation: one approach

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-29 15:14:33

On Tuesday 29 October 2002 02:52 pm, Jeff Garland wrote:
> 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.

The 'accuracy' problem is only part of the issue. The other problem is that 
it's hard to hide implementation details from Doxygen. The documented 
interface for a Boost library may be _very_ different from the actual 
implementation of that library. Doxygen needs to do what I say, not what I do 
when it comes to building the interface documentation :)

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

XSLT should have enough string-formatting capability to deal with this, given 
some arbitrary limit on the number of columns in preformatted text. But don't 
believe me until I've actually done it :)

        Doug