2,751
edits
Changes
Documentation Team/API Documentation (view source)
Revision as of 16:27, 14 June 2008
, 16:27, 14 June 2008editing Writing APIDOX in New Code
Packages are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the package as you go along. This means:
Packages are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the package as you go along. This means:
*Every package should have a package-level comment.
*Every package should have a package comment.
In the root directory of your packages create a file named Mainpage.dox. The first line of the comment must be the @mainpage doxygen directive followed by your package name. Next is the package comment wrapped in a docstring. Last are some apidox variables which help define the menu structure.
In the root directory of your packages create a file named Mainpage.dox. The first line of the comment must be the @mainpage doxygen directive followed by your package name. Next is the package comment wrapped in a docstring. Last are some apidox variables which help define the menu structure.
<code>
<code>
# @mainpage sugar
# @mainpage Sugar
<nowiki>"""</nowiki>
<nowiki>"""</nowiki>
Here is the description of the package named sugar.
Here is the description of the package named sugar.
*Every module should have a module comment.
A given module only needs a comment once in your source tree (or within one bunch of files that generate apidox together). Near the top of each module __init__.py file, create a @mainpage <module_name> directive followed by a description of what the module is for and what it defines. Wrap this up in docstring.
<code>
<nowiki>"""</nowiki>
@mainpage Control Panel
Here is a description of the module named controlPanel.
<nowiki>"""</nowiki>
</code>
These comments are just plain apidox comments wrapped up in """ """; there are no special markups needed like the @file for file comments.<br />Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:
<code>
<code>