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