2,751
edits
Changes
Jump to navigation
Jump to search
mLine 114:
Line 114: − + − + Line 128:
Line 128: + + − *Every module should have a module-level comment.+ − + + + + + − Nnear the top of your __init__.py file, write down what the module is for, vaguely what it defines. Wrap this up in a """ @namespace """ comment and you are set.+ − *Every module should have a comment. A given moduel only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. 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:
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>