documenting.xml revision 7db9f691a00ead175b03335457ca296a33ddf31b
297be3708069ef31814d6d75c0d71a50a78feb03Mark Andrews<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews<parentdocument href="./">Developer Documentation</parentdocument>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <p>Apache 2.0 uses <a href="http://www.doxygen.org/">Doxygen</a> to
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews document the APIs and global variables in the the code. This will explain
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews the basics of how to document using Doxygen.</p>
18fa75b694d056da4be3ebfc2185d007d4882752Automatic Updater<section id="brief"><title>Brief Description</title>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <p>To start a documentation block, use <code>/**</code><br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews To end a documentation block, use <code>*/</code></p>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <p>In the middle of the block, there are multiple tags we can
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews Description of this functions purpose<br />
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont @param parameter_name description<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews @return description<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews @deffunc signature of the function<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <p>The <code>deffunc</code> is not always necessary. DoxyGen does not
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews have a full parser in it, so any prototype that use a macro in the
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews return type declaration is too complex for scandoc. Those functions
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews require a <code>deffunc</code>. An example (using &gt; rather
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews than >):</p>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * return the final element of the pathname<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * @param pathname The path to get the final element of<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * @return the final element of the path<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * @tip Examples:<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * <pre><br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * "gum" -&gt; "gum"<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * "wi\\n32\\stuff" -&gt; "stuff"<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * </pre><br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * @deffunc const char * ap_filename_of_pathname(const char *pathname)<br />
18fa75b694d056da4be3ebfc2185d007d4882752Automatic Updater <p>At the top of the header file, always include:</p>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * @package Name of library header<br />
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <p>Doxygen uses a new HTML file for each package. The HTML files are named
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews {Name_of_library_header}.html, so try to be concise with your names.</p>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <p>For a further discussion of the possibilities please refer to
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <a href="http://www.doxygen.org/">the Doxygen site</a>.</p>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews</manualpage>