792a9ea1433c017cae367b7a42f7a667179c6f4fnd<?xml version="1.0" encoding="UTF-8" ?>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">

792a9ea1433c017cae367b7a42f7a667179c6f4fnd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd<manualpage>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd<relativepath href=".."/>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd<title>Documenting Apache 2.0</title>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd<summary>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>Apache 2.0 uses <a href="http://www.doxygen.org/">Doxygen</a> to

792a9ea1433c017cae367b7a42f7a667179c6f4fnd document the APIs and global variables in the the code. This will explain

792a9ea1433c017cae367b7a42f7a667179c6f4fnd the basics of how to document using Doxygen.</p>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd</summary>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd<section id="brief"><title>Brief Description</title>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>To start a documentation block, use <code>/**</code><br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd To end a documentation block, use <code>*/</code></p>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>In the middle of the block, there are multiple tags we can

792a9ea1433c017cae367b7a42f7a667179c6f4fnd use:</p>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <example>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd Description of this functions purpose<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd @param parameter_name description<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd @return description<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd @deffunc signature of the function<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd </example>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>The <code>deffunc</code> is not always necessary. DoxyGen does not

792a9ea1433c017cae367b7a42f7a667179c6f4fnd have a full parser in it, so any prototype that use a macro in the

792a9ea1433c017cae367b7a42f7a667179c6f4fnd return type declaration is too complex for scandoc. Those functions

792a9ea1433c017cae367b7a42f7a667179c6f4fnd require a <code>deffunc</code>. An example (using &amp;gt; rather

792a9ea1433c017cae367b7a42f7a667179c6f4fnd than &gt;):</p>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <example>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd /**<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* return the final element of the pathname<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* @param pathname The path to get the final element of<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* @return the final element of the path<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* @tip Examples:<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* &lt;pre&gt;<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* "/foo/bar/gum" -&amp;gt; "gum"<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* "/foo/bar/gum/" -&amp;gt; ""<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* "gum" -&amp;gt; "gum"<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* "wi\\n32\\stuff" -&amp;gt; "stuff"<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* &lt;/pre&gt;<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* @deffunc const char * ap_filename_of_pathname(const char *pathname)<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;*/

792a9ea1433c017cae367b7a42f7a667179c6f4fnd </example>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>At the top of the header file, always include:</p>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <example>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd /**<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;* @package Name of library header<br />

792a9ea1433c017cae367b7a42f7a667179c6f4fnd &nbsp;*/

792a9ea1433c017cae367b7a42f7a667179c6f4fnd </example>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>Doxygen uses a new HTML file for each package. The HTML files are named

792a9ea1433c017cae367b7a42f7a667179c6f4fnd {Name_of_library_header}.html, so try to be concise with your names.</p>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>For a further discussion of the possibilities please refer to

792a9ea1433c017cae367b7a42f7a667179c6f4fnd <a href="http://www.doxygen.org/">the Doxygen site</a>.</p>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd</section>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd</manualpage>

792a9ea1433c017cae367b7a42f7a667179c6f4fnd