documenting

来自「Apache V2.0.15 Alpha For Linuxhttpd-2_0_」· 代码 · 共 44 行

Apache 2.0 is using ScanDoc to document the API's and global variables in 
the code.  This will explain the basics of how to document using Scandoc.

To start a scandoc block, use /**
To end a scandoc block, use */

In the middle of the block, there are multiple tags we can use:

 Description of this functions purpose
 @param parameter_name description
 @tip Any information the programmer should know
 @deffunc function prototype.

The deffunc is not always necessary.  ScanDoc 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:

/**
 * 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, we 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