Changes

m
editing Writing APIDOX in New Code
Line 114: Line 114:  
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.
Line 128: Line 128:        +
*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.
   −
*Every module should have a module-level comment.
+
<code>
 
+
  <nowiki>"""</nowiki>
 +
  @mainpage Control Panel
 +
  Here is a description of the module named controlPanel.
 +
  <nowiki>"""</nowiki>
 +
</code>
   −
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.
+
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:
      
<code>
 
<code>
2,751

edits