Commit 8d2df7ff authored by William A. Rowe Jr's avatar William A. Rowe Jr
Browse files 

  Move API.html over to manual/developer, begin some cleanup.

  Could a DoxyGen'er please update the guidlines in documenting.html?


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91108 13f79535-47bb-0310-9956-ffa450edef68
parent b9f5c7a4

docs/manual/developer/documenting

deleted100644 → 0
+0 −43
Original line number Diff line number Diff line 
Apache 2.0 is using ScanDoc to document the API's and global variables in 

the code.  This will explain the basics of how to document using Scandoc.



To start a scandoc block, use /**

To end a scandoc block, use */



In the middle of the block, there are multiple tags we can use:



 Description of this functions purpose

 @param parameter_name description

 @tip Any information the programmer should know

 @deffunc function prototype.



The deffunc is not always necessary.  ScanDoc 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 deffunc.



An example:



/**

 * return the final element of the pathname

 * @param pathname The path to get the final element of

 * @return the final element of the path

 * @tip Examples:

 * <PRE>

 *                 "/foo/bar/gum"   -> "gum"

 *                 "/foo/bar/gum/"  -> ""

 *                 "gum"            -> "gum"

 *                 "wi\\n32\\stuff" -> "stuff"

 * </PRE>

 * @deffunc const char * ap_filename_of_pathname(const char *pathname)

 */



At the top of the header file, we always include



/**

 * @package Name of library header

 */



ScanDoc 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

docs/manual/developer/documenting.html

0 → 100644
+64 −0
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>

<head>

<title>Documenting Apache 2.0</title>

</head>

<!-- Background white, links blue (unvisited), navy (visited), red (active) -->

<BODY

 BGCOLOR="#FFFFFF"

 TEXT="#000000"

 LINK="#0000FF"

 VLINK="#000080"

 ALINK="#FF0000"

>



<!--#include virtual="header.html" -->



<h1 align="center">Documentating Apache 2.0</h1>



<p>Apache 2.0 uses DoxyGen to document the API's and global variables in the

   the code.  This will explain the basics of how to document using DoxyGen.



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

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



<p>In the middle of the block, there are multiple tags we can use:</p>

<pre>

    Description of this functions purpose

    @param parameter_name description

</p>



<p>The deffunc 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 deffunc.</p>



<p>An example (using &&gt; rather than &gt;):</p>

<pre>

/**

 * return the final element of the pathname

 * @param pathname The path to get the final element of

 * @return the final element of the path

 * @tip Examples:

 * &lt;pre&gt;

 *                 "/foo/bar/gum"   -&&gt; "gum"

 *                 "/foo/bar/gum/"  -&&gt; ""

 *                 "gum"            -&&gt; "gum"

 *                 "wi\\n32\\stuff" -&&gt; "stuff"

 * &lt;/pre&gt;

 * @deffunc const char * ap_filename_of_pathname(const char *pathname)

 */

</pre>



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

<pre>

/**

 * @package Name of library header

 */

</pre>



<p>ScanDoc 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>

 

<!--#include virtual="footer.html" -->

</body>

</html>

docs/manual/developer/index.html

+16 −4
Original line number Diff line number Diff line
@@ -16,10 +16,22 @@ 


<h1 align="center">Developer Documentation for Apache-2.0</h1>



<p><a href="hooks.html">Apache Hook Functions</a></p>

<p><a href="modules.html">Converting Apache 1.3 Modules to Apache 2.0</a></p>

<p><a href="debugging.html">Debugging Memory Allocation in APR</a></p>

<p><a href="../misc/API.html">Apache 1.3 API Notes</a></p>

<p>Many of the documents on these Developer pages are lifted from Apache 1.3's

   documentation.  While they are all being updated to Apache 2.0, they are

   in different stages of progress.  Please be patient, and point out any

   discrepancies or errors on the developer/ pages directly to the 

   dev@httpd.apache.org mailing list.</p>



<h3>Topics</h3>

<dl>

   <dt><a href="API.html">Apache 2.0 API Notes</a></dt>

      <dd>Overview of Apache's Application Programming Interface.</dd>

   <dt><a href="hooks.html">Apache Hook Functions</a></dt>

   <dt><a href="modules.html">Porting Apache 1.3 Modules</a></dt>

   <dt><a href="debugging.html">Debugging Memory Allocation</a></dt>

   <dt><a href="documenting.html">Documenting Apache 2.0</a></dt>

</dl>



<!--#include virtual="footer.html" -->

</body>

</html>

docs/manual/misc/API.html

deleted100644 → 0
+0 −1161

File deleted.

Preview size limit exceeded, changes collapsed.

docs/manual/misc/index.html

+0 −6
Original line number Diff line number Diff line
@@ -20,12 +20,6 @@ 
  Apache web server development project.

  </P>

  <DL>

   <DT><A

        HREF="API.html"

       >API</A>

   </DT>

   <DD>Description of Apache's Application Programming Interface.

   </DD>

   <DT><A HREF="custom_errordocs.html">How to use XSSI and Negotiation 

	for custom ErrorDocuments</A>

   </DT>