Re: [boost] Reference documentation: one approach

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-30 11:10:23

On Tuesday 29 October 2002 03:05 pm, Douglas Gregor wrote:
> [I'm going to try to pin down my set of requirements for Boost reference
> documentation so that we can try to evaluate potential solutions more
> objectively]

Here's my one, big requirement for reference documentation:

- Must take annotated C++ structure and produce reference documentation 
similar in style to the C++ standard.

By annotated C++ structure, I mean some code or markup that gives the details 
of each C++ entity: a function would have its name, return type, and 
parameter list (each parameter would have its type, name, and default 
argument), along with requires/returns/throws/etc. clauses. 

Annotated C++ structure could be extracted with a tool like Synopsis or 
Doxygen, perhaps, but we need a common format that developers can write 
directly (for those outlandish libraries where the implementation is so 
different from the interface that extraction doesn't help).

The reference documentation output should:
  - have a synopsis for each header, including a listing of all classes/class 
templates and free functions/function templates (with links to the 
documentation of each)
  - have the definition of each class/class templates with a listing of all 
associated types, member functions, and free functions (with links to the 
documentation of each)
  - have detailed documentation for each function using the standard's 
effects/postconditions/throws/etc. clauses
  - provide an index of all classes, functions, and namespaces
  - link references to other boost classes within the reference documentation 

        Doug