2,751
edits
Changes
Documentation Team/API Documentation (view source)
Revision as of 15:23, 14 June 2008
, 15:23, 14 June 2008editing Writing APIDOX in New Code
== Writing APIDOX in New Code ==
== Writing APIDOX in New Code ==
The following little checklist should get you through the worst of writing apidox.
The following little checklist should get you through the worst of writing apidox.
'''1. Write apidox as you code'''
'''1. Write apidox as you code.'''
The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.
The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.
This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.
This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.
'''2. Document your modules completely'''
'''2. Document your packages completely'''
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.
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>
# @mainpage sugar
<nowiki>"""</nowiki>
Here is the description of the package named sugar.
<nowiki>"""</nowiki>
//DOXYGEN_SET_PROJECT_NAME=Sugar
//DOXYGEN_NAME=Sugar-module
//DOXYGEN_EXCLUDE
</code>
*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:
*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:
== Fixing APIDOX in Old Code ==
== Fixing APIDOX in Old Code ==
<!--
Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)
Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)