| Line 1: |
Line 1: |
| | + | {{draft}} |
| | == Definition == | | == Definition == |
| | | | |
| Line 126: |
Line 127: |
| | //DOXYGEN_EXCLUDE | | //DOXYGEN_EXCLUDE |
| | </code> | | </code> |
| − |
| |
| | | | |
| | *Every module should have a module comment. | | *Every module should have a module comment. |
| Line 138: |
Line 138: |
| | </code> | | </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:
| + | *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. |
| | | | |
| − | <code>
| |
| − | """
| |
| − | The Ungulate methods collects classes and methods
| |
| − | pertaining to hooved animals.
| |
| − | """
| |
| | | | |
| − | namespace Ungulate {
| |
| − | </code>
| |
| − |
| |
| − | :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.
| |
| | | | |
| | '''3. Watch this space!''' | | '''3. Watch this space!''' |