RE: [boost] Reference documentation: one approach

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-10-30 13:54:02

> I wouldn't give up on generation just yet, but we can't _require_ generation. 

Absolutely agree.

> Well, I can't use generation, because there is no way that any program is 
> going to take function/function_template.hpp as input and come back with 
> sensible documentation.

Right, I have this problem as well.  The thing is you can override
most of the implementation context issues with the Doxygen syntax.  
For example, you can do the following in doxygen syntax and get
documentation even if the parser never sees a class 'SomeClass' and 
method foo:

/*! @fn const char *SomeClass::foo(char c,int n) 
 *  @brief Brief description for SomeClass::foo
 * ...
 */

Now normally you don't want to do this b/c you might mistype the 
'code part', but if you are trying to hide the fact that this is 
method is actually generated into a base class in the 
implementation using a policy template or something, it will make 
sense to do this.  And in most case I think I still want this
specification in the code for keeping things in sync.
 
> My suggestion is to have an intermediate representation of C++ from which we 
> can generate the reference documentation. That intermediate representation 
> can be hand-written or generated from a tool like Doxygen or Synopsis.

Might be interesting to compare the doxygen XML tags with your set of
tags.  I'll give this a try later and post the results.

Jeff