Sugar Labs

Documentation Team/API Documentation: Difference between revisions

← Older edit
Dfarning (talk | contribs)
2,751 edits
m editing Writing APIDOX in New Code
m categorize
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<noinclude>[[Category:API]]
[[Category:Documentation]]
</noinclude>{{draft}}
== Definition ==
== Definition ==


Line 126: Line 129:
   //DOXYGEN_EXCLUDE  
   //DOXYGEN_EXCLUDE  
</code>
</code>


*Every module should have a module comment.
*Every module should have a module comment.
Line 138: Line 140:
</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!'''
Line 171: Line 151:
'''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 ==
Line 402: Line 382:
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
Line 418: Line 398:
</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
Line 447: Line 427:
: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.
-->
-->
[[Category:Documentation]]
Retrieved from "https://wiki.sugarlabs.org/go/Documentation_Team/API_Documentation"