documenting.xml revision 3457da8a00fcade7e2971bbc3d545ecfd32b2da9
<?xml version="1.0" encoding="UTF-8" ?>
<!-- $LastChangedRevision$ -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<manualpage metafile="documenting.xml.meta">
<parentdocument href="./">Developer Documentation</parentdocument>
<title>Documenting Apache 2.0</title>
<summary>
document the APIs and global variables in the code. This will explain
the basics of how to document using Doxygen.</p>
</summary>
<section id="brief"><title>Brief Description</title>
<p>To start a documentation block, use <code>/**</code><br />
To end a documentation block, use <code>*/</code></p>
<p>In the middle of the block, there are multiple tags we can
use:</p>
<example>
Description of this functions purpose<br />
@param parameter_name description<br />
@return description<br />
@deffunc signature of the function<br />
</example>
<p>The <code>deffunc</code> 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 <code>deffunc</code>. An example (using &gt; rather
than >):</p>
<example>
/**<br />
* return the final element of the pathname<br />
* @param pathname The path to get the final element of<br />
* @return the final element of the path<br />
* @tip Examples:<br />
* <pre><br />
* "gum" -&gt; "gum"<br />
* "wi\\n32\\stuff" -&gt; "stuff"<br />
* </pre><br />
* @deffunc const char * ap_filename_of_pathname(const char *pathname)<br />
*/
</example>
<p>At the top of the header file, always include:</p>
<example>
/**<br />
* @package Name of library header<br />
*/
</example>
<p>Doxygen 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>
<p>For a further discussion of the possibilities please refer to
</section>
</manualpage>