C++ API documentor?

[mcox05]

Does anyone know of any software (if any) that has been built to compile APIs of c++ projects ... something comparable to JavaDocs in Java. Any info would be awesome.

 

[Salem]

http://en.wikipedia.org/wiki/Doxygen

--
If you dance barefoot on the broken glass of undefined behaviour, you've got to expect the occasional cut.

 

[ArkM]

Direct link to Doxygen:

http://www.stack.nl/~dimitri/doxygen/index.html

Doxygen the Magnificent...

 

[mcox05]

muchas gracias!

 

[xwb]

Remember that the documentation generated is only as good as the comments and it normally doesn't say how the whole thing hangs together. You also have to follow the rules of the package. For instance, I tend to layout programs like

// routine description
void routine_name (
   type parameter  // parameter description
,  type parameter  // parameter description
)
{
}

which is absolutely great for maintenance since it is just a one liner to add a new parameter. Diffs will show that this is the only line that has changed and there is a description of what the parameter does.

All the documentation engines I've tried (javadoc, doxygen and the C# one produced by MS) cannot handle this. They would rather have

// routine description
// parameter description
// parameter description
void routine (...

What happens in maintenance is that parameters are added to the routine without the comment being updated. When you're under pressure to get a fix out, looking above the routine declaration is not something you would normally do. Gets even worse when a routine has lots of parameters. The new parameter has to be inserted at the correct point in the description otherwise the comment will not match the parameters. Often this is left as a TODO and the description never gets updated. It could be part of the code review but in a complex fix, this is often skipped.

 

[cpjust]

Doxygen uses the same format as Javadoc, so the function documentation should look like this:

/** [i]short description[/i]
 *  [i]long description[/i]
 *
 *  @param param1 [IN] - blah blah blah.
 *
 *  @param param2 [IN/OUT] - blah blah blah.
 *
 *  @return - blah blah bhal.
 *
 *  @throws [i]exception type[/i] - blah blah blah.
 */

I don't use your form of documenting, but you might try using the doxygen single-line comment style to see if that helps.

type  name;  /**[COLOR=red]<[/color] blah blah blah. */

 

[macro187]

Dear xwb,

1. Enable the JAVADOC_AUTOBRIEF option in your doxygen config

2. Do this:

/// Brief description
///
/// Detailed description is optional and
/// goes here.
void routine_name (
   type parameter  ///< parameter description
,  type parameter  ///< parameter description
)
{
}

3. Profit. (or whatever)

Ron

 

[xwb]

Thanks - I'll try that.