mirror of
https://github.com/apache/httpd.git
synced 2025-11-03 17:53:20 +03:00
69c1a5c854
Trim trailing whitespace... no func change git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1174747 13f79535-47bb-0310-9956-ffa450edef68
85 lines
3.2 KiB
XML
85 lines
3.2 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $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
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
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>
|
|
<p>Apache 2.0 uses <a href="http://www.doxygen.org/">Doxygen</a> to
|
|
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 />
|
|
* "/foo/bar/gum" -&gt; "gum"<br />
|
|
* "/foo/bar/gum/" -&gt; ""<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
|
|
<a href="http://www.doxygen.org/">the Doxygen site</a>.</p>
|
|
</section>
|
|
</manualpage>
|
|
|