home *** CD-ROM | disk | FTP | other *** search
/ PC World 2003 November / PCWorld_2003-11_cd.bin / Komunik / apache / apache_2.0.47-win32-x86-no_ssl.msi / Data.Cab / F250730_documenting.xml < prev    next >
Encoding:
Extensible Markup Language  |  2003-04-15  |  2.5 KB  |  67 lines
  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. <parentdocument href="./">Developer Documentation</parentdocument>
  7.  
  8. <title>Documenting Apache 2.0</title>
  9.  
  10. <summary>
  11.     <p>Apache 2.0 uses <a href="http://www.doxygen.org/">Doxygen</a> to
  12.     document the APIs and global variables in the the code. This will explain
  13.     the basics of how to document using Doxygen.</p>
  14. </summary>
  15.  
  16. <section id="brief"><title>Brief Description</title>
  17.     <p>To start a documentation block, use <code>/**</code><br />
  18.     To end a documentation block, use <code>*/</code></p>
  19.  
  20.     <p>In the middle of the block, there are multiple tags we can
  21.     use:</p>
  22.  
  23.     <example>
  24.       Description of this functions purpose<br />
  25.       @param parameter_name description<br />
  26.       @return description<br />
  27.       @deffunc signature of the function<br />
  28.     </example>
  29.       
  30.     <p>The <code>deffunc</code> is not always necessary. DoxyGen does not
  31.     have a full parser  in it, so any prototype that use a macro in the
  32.     return type declaration is too complex for scandoc. Those functions
  33.     require a <code>deffunc</code>. An example (using &gt; rather
  34.     than >):</p>
  35.  
  36.     <example>
  37.       /**<br />
  38.   * return the final element of the pathname<br />
  39.   * @param pathname The path to get the final element of<br />
  40.   * @return the final element of the path<br />
  41.   * @tip Examples:<br />
  42.   * <pre><br />
  43.   *                 "/foo/bar/gum"   -&gt; "gum"<br />
  44.   *                 "/foo/bar/gum/"  -&gt; ""<br />
  45.   *                 "gum"            -&gt; "gum"<br />
  46.   *                 "wi\\n32\\stuff" -&gt; "stuff"<br />
  47.   * </pre><br />
  48.   * @deffunc const char * ap_filename_of_pathname(const char *pathname)<br />
  49.   */
  50.     </example>
  51.  
  52.     <p>At the top of the header file, always include:</p>
  53.     <example>
  54.       /**<br />
  55.   * @package Name of library header<br />
  56.   */
  57.     </example>
  58.  
  59.     <p>Doxygen uses a new HTML file for each package. The HTML files are named
  60.     {Name_of_library_header}.html, so try to be concise with your names.</p>
  61.  
  62.     <p>For a further discussion of the possibilities please refer to
  63.     <a href="http://www.doxygen.org/">the Doxygen site</a>.</p>
  64. </section>
  65. </manualpage>
  66.  
  67.