8,288
edits
Changes
Jump to navigation
Jump to search
mLine 1:
Line 1: + + + Line 114:
Line 117: − + − + Line 127:
Line 130: − + − + − − − − 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: − + − The Ungulate methods collects classes and methods + − pertaining to hooved animals. + − + − − namespace Ungulate { − :In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).+ − + − <code> − """ − The Ungulate namespace collects classes and methods − pertaining to hooved animals. − """ − class Mammal; − namespace Ungulate { − </code> − :There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting. − *Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly).<br />The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately. − *Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply. Line 166:
Line 151: − + Line 397:
Line 382: − + Line 413:
Line 398: − + Line 442:
Line 427: − [[Category:Documentation]]
Documentation Team/API Documentation (view source)
Revision as of 15:34, 2 November 2011
, 15:34, 2 November 2011categorize
<noinclude>[[Category:API]]
[[Category:Documentation]]
</noinclude>{{draft}}
== Definition ==
== Definition ==
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.
</code>
</code>
*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>
<code>
"""
<nowiki>"""</nowiki>
@mainpage Control Panel
Here is a description of the module named controlPanel.
"""
<nowiki>"""</nowiki>
</code>
</code>
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly).<br />The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
'''3. Watch this space!'''
'''3. Watch this space!'''
'''4. Write a main page for your application.'''
'''4. Write a main page for your application.'''
This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.
This is usually done in a separate file in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.
== Fixing APIDOX in Old Code ==
== Fixing APIDOX in Old Code ==
Very useful, in fact, for the reader who is wondering
Very useful, in fact, for the reader who is wondering
how exactly to use the class in a straightforward way.
how exactly to use the class in a straightforward way.
Most classes in {{path|kdelibs/kdecore}} have example code.
Most classes have example code.
One way to write example code is to use @code and @endcode around
One way to write example code is to use @code and @endcode around
</code>
</code>
This is how most of the examples in {{path|kdelibs}}
This is how most of the examples
are done, actually. It works reasonably well, you can pare the
are done, actually. It works reasonably well, you can pare the
example down to something really minimal and leave out all the
example down to something really minimal and leave out all the
:This is a list of all available documentation tags of doxygen, from the official site. Note that the list uses a backslash in front of a tag, while this page always used the at sign. Both are allowed, but for KDE you should use the at sign to stay consistent within KDE.
:This is a list of all available documentation tags of doxygen, from the official site. Note that the list uses a backslash in front of a tag, while this page always used the at sign. Both are allowed, but for KDE you should use the at sign to stay consistent within KDE.
-->
-->