Documentation Team/API Documentation: Difference between revisions

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:

*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.

<code>

# @mainpage ~~sugar~~

# @mainpage Sugar

Here is the description of the package named sugar.

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>

@mainpage Control Panel

Here is a description of the module named controlPanel.

</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>

@@ 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:
-*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.
 <code>
-   # @mainpage sugar
+   # @mainpage Sugar
    <nowiki>"""</nowiki>
    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>