RE: [boost] Reference documentation: one approach

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

> 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

Well I had given up on generation, but maybe I was premature.  One topic we might
discuss is the format for putting these sorts of comments in the code. I would
suggest we recommend we Doxygen 'syntax' for this (this would be a recommendation
not a hard requirement).  There are several reasons:

1) It is well documented and widely used
2) Apparently both Doxygen and Synopsis will support it (Dave does Synopsis specify it's own format for this -- I didn't see it on
the website?)
3) It probably covers 95% of what we need.
4) It is pretty logical

I believe that the doxygen commenting format will handle almost all of Doug's list and those that it doesn't can be added.  So,
for example we a fully annotated function would look something like:

//! This is the brief comment for a function
/*! This is the long comment for the function.
    ...
    ... still the long comment....
  @param foo Description of the foo parameter
  @param bar Description of the bar parameter
  @return Description of the return value
  @pre Precondition 1
  @pre Precondition 2
  @post Postcondition 1
  @throws Exception commentary

  -- you get the idea
*/
int f(int foo, double bar);

There are a couple of things the standard doxygen syntax doesn't include (eg: requires), but the extension is pretty
straightforward.

Jeff