| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta name="generator" content="HTML Tidy, see www.w3.org" /> |
| |
| <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> |
| |
| <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 |
| |
| |
| <br /> |
| 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. |
| |
| <br /> |
| An example (using &gt; rather than >): |
| </pre> |
| <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" -&gt; "gum" |
| * "/foo/bar/gum/" -&gt; "" |
| * "gum" -&gt; "gum" |
| * "wi\\n32\\stuff" -&gt; "stuff" |
| * </pre> |
| * @deffunc const char * ap_filename_of_pathname(const char *pathname) |
| */ |
| </pre> |
| <pre> |
| <br /> |
| At the top of the header file, always include: |
| </pre> |
| <pre> |
| /** |
| * @package Name of library header |
| */ |
| </pre> |
| <pre> |
| <br /> |
| 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. |
| |
| <!--#include virtual="footer.html" --> |
| </pre> |
| </body> |
| </html> |
| |
