Documenting Apache 2.0

Available Languages: en

+ +

Apache 2.0 uses Doxygen to + document the APIs and global variables in the code. This will explain + the basics of how to document using Doxygen.

Brief Description

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 + @return description + @deffunc signature of the function +

+ +

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 + */ +

+ +

Doxygen 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.

+ +

For a further discussion of the possibilities please refer to + the Doxygen site.