| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <html> |
| <head> |
| <title>Documenting Apache 2.0</title> |
| </head> |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| |
| <!--#include virtual="header.html" --> |
| |
| <h1 align="center">Documentating Apache 2.0</h1> |
| |
| <p>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. |
| |
| <p>To start a documentation block, use /**<br /> |
| To end a documentation block, use */</p> |
| |
| <p>In the middle of the block, there are multiple tags we can use:</p> |
| <pre> |
| Description of this functions purpose |
| @param parameter_name description |
| </p> |
| |
| <p>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.</p> |
| |
| <p>An example (using &> rather than >):</p> |
| <pre> |
| /** |
| * 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) |
| */ |
| </pre> |
| |
| <p>At the top of the header file, always include:</p> |
| <pre> |
| /** |
| * @package Name of library header |
| */ |
| </pre> |
| |
| <p>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.</p> |
| |
| <!--#include virtual="footer.html" --> |
| </body> |
| </html> |
