documenting.xml revision 860b4efe27e7c1c9a2bf5c872b29c90f76849b51
792a9ea1433c017cae367b7a42f7a667179c6f4fnd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
031b91a62d25106ae69d4693475c79618dd5e884fielding Licensed to the Apache Software Foundation (ASF) under one or more
031b91a62d25106ae69d4693475c79618dd5e884fielding contributor license agreements. See the NOTICE file distributed with
031b91a62d25106ae69d4693475c79618dd5e884fielding this work for additional information regarding copyright ownership.
031b91a62d25106ae69d4693475c79618dd5e884fielding The ASF licenses this file to You under the Apache License, Version 2.0
031b91a62d25106ae69d4693475c79618dd5e884fielding (the "License"); you may not use this file except in compliance with
031b91a62d25106ae69d4693475c79618dd5e884fielding the License. You may obtain a copy of the License at
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd Unless required by applicable law or agreed to in writing, software
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd distributed under the License is distributed on an "AS IS" BASIS,
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd See the License for the specific language governing permissions and
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd limitations under the License.
c82fca6d3f5608b946f18d37e8710b1d71e3478dnd<parentdocument href="./">Developer Documentation</parentdocument>
792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>Apache 2.0 uses <a href="http://www.doxygen.org/">Doxygen</a> to
3457da8a00fcade7e2971bbc3d545ecfd32b2da9trawick document the APIs and global variables in the code. This will explain
792a9ea1433c017cae367b7a42f7a667179c6f4fnd the basics of how to document using Doxygen.</p>
792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>To start a documentation block, use <code>/**</code><br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>In the middle of the block, there are multiple tags we can
792a9ea1433c017cae367b7a42f7a667179c6f4fnd Description of this functions purpose<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd @param parameter_name description<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd @return description<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd @deffunc signature of the function<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd </example>
792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>The <code>deffunc</code> is not always necessary. DoxyGen does not
792a9ea1433c017cae367b7a42f7a667179c6f4fnd have a full parser in it, so any prototype that use a macro in the
792a9ea1433c017cae367b7a42f7a667179c6f4fnd return type declaration is too complex for scandoc. Those functions
792a9ea1433c017cae367b7a42f7a667179c6f4fnd require a <code>deffunc</code>. An example (using &gt; rather
792a9ea1433c017cae367b7a42f7a667179c6f4fnd than >):</p>
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * return the final element of the pathname<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * @param pathname The path to get the final element of<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * @return the final element of the path<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * @tip Examples:<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * <pre><br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * "gum" -&gt; "gum"<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * "wi\\n32\\stuff" -&gt; "stuff"<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * </pre><br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * @deffunc const char * ap_filename_of_pathname(const char *pathname)<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd </example>
792a9ea1433c017cae367b7a42f7a667179c6f4fnd * @package Name of library header<br />
792a9ea1433c017cae367b7a42f7a667179c6f4fnd </example>
792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>Doxygen uses a new HTML file for each package. The HTML files are named
792a9ea1433c017cae367b7a42f7a667179c6f4fnd {Name_of_library_header}.html, so try to be concise with your names.</p>
792a9ea1433c017cae367b7a42f7a667179c6f4fnd <p>For a further discussion of the possibilities please refer to
792a9ea1433c017cae367b7a42f7a667179c6f4fnd <a href="http://www.doxygen.org/">the Doxygen site</a>.</p>
792a9ea1433c017cae367b7a42f7a667179c6f4fnd</manualpage>