Apache 2.0 uses DoxyGen to document the API's and global variables in the the code. This will explain the basics of how to document using DoxyGen.
To start a documentation block, use /**
To end a documentation block, use */
In the middle of the block, there are multiple tags we can use:
Description of this functions purpose
@param parameter_name description
The deffunc is not always necessary. DoxyGen does not have a full parser
in it, so any prototype that use a macro in the return type declaration
is too complex for scandoc. Those functions require a deffunc.
An example (using &> rather than >):
/**
* return the final element of the pathname
* @param pathname The path to get the final element of
* @return the final element of the path
* @tip Examples:
* <pre>
* "/foo/bar/gum" -&> "gum"
* "/foo/bar/gum/" -&> ""
* "gum" -&> "gum"
* "wi\\n32\\stuff" -&> "stuff"
* </pre>
* @deffunc const char * ap_filename_of_pathname(const char *pathname)
*/
At the top of the header file, always include:
/**
* @package Name of library header
*/
ScanDoc uses a new html file for each package. The html files are named
{Name_of_library_header}.html, so try to be concise with your names.