granicus.if.org Git - apache/blob - docs/manual/developer/documenting.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4
   5 <manualpage metafile="documenting.xml.meta">
   6 <relativepath href=".."/>
   7 <parentdocument href="./">Developer Documentation</parentdocument>
   8
   9 <title>Documenting Apache 2.0</title>
  10
  11 <summary>
  12     <p>Apache 2.0 uses <a href="http://www.doxygen.org/">Doxygen</a> to
  13     document the APIs and global variables in the the code. This will explain
  14     the basics of how to document using Doxygen.</p>
  15 </summary>
  16
  17 <section id="brief"><title>Brief Description</title>
  18     <p>To start a documentation block, use <code>/**</code><br />
  19     To end a documentation block, use <code>*/</code></p>
  20
  21     <p>In the middle of the block, there are multiple tags we can
  22     use:</p>
  23
  24     <example>
  25       Description of this functions purpose<br />
  26       @param parameter_name description<br />
  27       @return description<br />
  28       @deffunc signature of the function<br />
  29     </example>
  30
  31     <p>The <code>deffunc</code> is not always necessary. DoxyGen does not
  32     have a full parser  in it, so any prototype that use a macro in the
  33     return type declaration is too complex for scandoc. Those functions
  34     require a <code>deffunc</code>. An example (using &amp;gt; rather
  35     than &gt;):</p>
  36
  37     <example>
  38       /**<br />
  39  &nbsp;* return the final element of the pathname<br />
  40  &nbsp;* @param pathname The path to get the final element of<br />
  41  &nbsp;* @return the final element of the path<br />
  42  &nbsp;* @tip Examples:<br />
  43  &nbsp;* &lt;pre&gt;<br />
  44  &nbsp;*                 "/foo/bar/gum"   -&amp;gt; "gum"<br />
  45  &nbsp;*                 "/foo/bar/gum/"  -&amp;gt; ""<br />
  46  &nbsp;*                 "gum"            -&amp;gt; "gum"<br />
  47  &nbsp;*                 "wi\\n32\\stuff" -&amp;gt; "stuff"<br />
  48  &nbsp;* &lt;/pre&gt;<br />
  49  &nbsp;* @deffunc const char * ap_filename_of_pathname(const char *pathname)<br />
  50  &nbsp;*/
  51     </example>
  52
  53     <p>At the top of the header file, always include:</p>
  54     <example>
  55       /**<br />
  56  &nbsp;* @package Name of library header<br />
  57  &nbsp;*/
  58     </example>
  59
  60     <p>Doxygen uses a new HTML file for each package. The HTML files are named
  61     {Name_of_library_header}.html, so try to be concise with your names.</p>
  62
  63     <p>For a further discussion of the possibilities please refer to
  64     <a href="http://www.doxygen.org/">the Doxygen site</a>.</p>
  65 </section>
  66 </manualpage>
  67