RE: [boost] Reference documentation: one approach

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-10-29 15:57:58

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

Yes this is true, but sometimes users just need to browse and 
understand the implementation better.  And the hiding can be
controlled, but I'm really not going to go there.  Fact is that 
if we move toward XML those of us with an interest might be able
to extract XML using Doxygen and transform it into other XML-based
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.  
> ...
> 
> 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 :)

Beleive me I won't ;-)  However, looking at your XML it looks like 
it might be fairly easy to create something like:

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

However, I suspect there will be complications to allow for
handling of simpler cases.

Oh and thanks for posting this now.  This is something that will
help me with my little homework assignment from last week :-)

Jeff