Get an mbed!
Subscribe to the mailing list
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.
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) {...}
Please log in to post a comment.
The reference for how to use documentation in mbed can be found here: http://mbed.org/cookbook/Documenting-a-Library