AutodocSyntax

Page last updated 28 Feb 2010, by Simon Ford. 1 reply api, documentation, doxygen

Auto-documentation is a great way to document APIs to allow simple rendering of libraries for users to quickly pick up and use. Importantly, that where it stops; it is not good to try and use it to document implementations, or entire documentation. So, we'll focus it on "API documentation".

For our internal documentation we've been using NaturalDocs with good results, but as part of making auto-documentation facilities available to all users we're leaning towards the more standard Javadoc style as supported by Doxygen.

Doxygen supports lots of variants of documentation markup and configuration options, so my preference is to set a precedent on how it is done to make it simple and consistent. Here is my draft of the spec for documentation based on Doxygen.

  • Use Javadoc style /** opener to distinguish from "undocumented" comments that use /* or //
  • Make the first line be a brief description of the function or class (JAVADOC_AUTOBRIEF = YES)
  • Document before the function (i.e. function association is implicitly referenced)
  • Use @ markup for attributes (@param, @return)

Example:

/** A brief description of the function foo
 * 
 * More details about the function goes here
 * and here
 *
 * @param x a variable used by foo
 * @return something magical done with x   
 */
int foo(int x) {...}

1 comment

Dan Ros
02 Nov 2010

The reference for how to use documentation in mbed can be found here: http://mbed.org/cookbook/Documenting-a-Library

You need to log in to post a comment