rbb 00/07/29 07:30:29
Added: htdocs/manual/developer documenting Log: Add a small doc on how to document the APIs for use with ScanDoc. Revision Changes Path 1.1 httpd-docs-2.0/htdocs/manual/developer/documenting Index: documenting =================================================================== 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
