Changes

== Definition ==

== Definition ==

 

'''API (''Application Programming Interface'') documentation''' is documentation that applies to ''a program'' and its interfaces. It is documentation that explains to a developer who is going to work with the program, or a developer who is going to work on a program, how things work and what methods are there to call.

'''API (''Application Programming Interface'') documentation''' is documentation that applies to ''a program'' and its interfaces. It is documentation that explains to a developer who is going to work with the program, or a developer who is going to work on a program, how things work and what methods are there to call.

Good apidox take some effort to write -- but less effort than good ''user'' documentation, since you as a developer are writing for another developer, and explaining how code works and what it is supposed to do. So your audience is clear to start with. The benefits of apidox come when someone else (or maybe even you several months later) needs to (re)use the code, or extend it. Good apidox means that someone new can show up, understand your code, and produce meaningful patches (that is, ''help'') all the more quickly. Especially for libraries, good apidox make the library usable as a black box (and that's how they should be) because all the needed documentation is available in the apidox and not hidden in the (perhaps inaccessible) code.

Good apidox take some effort to write -- but less effort than good ''user'' documentation, since you as a developer are writing for another developer, and explaining how code works and what it is supposed to do. So your audience is clear to start with. The benefits of apidox come when someone else (or maybe even you several months later) needs to (re)use the code, or extend it. Good apidox means that someone new can show up, understand your code, and produce meaningful patches (that is, ''help'') all the more quickly. Especially for libraries, good apidox make the library usable as a black box (and that's how they should be) because all the needed documentation is available in the apidox and not hidden in the (perhaps inaccessible) code.

 

== Preamble ==

== Preamble ==

 

APIDOX are what make a program accessible to other contributors. They are not essential, but they certainly help a great deal for new people who want to work on your code, or better yet, re-use it elsewhere with a minimum of modification.

APIDOX are what make a program accessible to other contributors. They are not essential, but they certainly help a great deal for new people who want to work on your code, or better yet, re-use it elsewhere with a minimum of modification.

This document is going to try to prevent the apidox process from becoming exhausting, by giving straightforward tips about how to write apidox.

This document is going to try to prevent the apidox process from becoming exhausting, by giving straightforward tips about how to write apidox.

 

== APIDOX Basics ==

== APIDOX Basics ==

Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.

Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.

APIDOX are written in python docstring comments. These comments are surrounded by <nowiki>"""</nowiki> (quote, quote, quote) -- that's what makes them special. The rest of the content of the comment is just plain text describing a part of your program. The plain text is interpreted by the Doxygen processor, so that you can write accurate descriptions of parameters, return types, and do some basic text markup. But documentation can be very straighforward: just write down what a method does, surrounded by <nowiki>"""</nowiki> and <nowiki>"""</nowiki>, like this:

APIDOX consist of two types of comments python docstrings and doxygen directives. These docstrings are surrounded by <nowiki>"""</nowiki> (quote, quote, quote) -- that's what makes them special. The rest of the content of the comment is just plain text describing a part of your program. The plain text is interpreted by the Doxygen processor, so that you can write accurate descriptions of parameters, return types, and do some basic text markup.

 

 

But documentation can be very straightforward: just write down what a method does, surrounded by <nowiki>"""</nowiki> and <nowiki>"""</nowiki>, like this:

<code>

<code>

== Writing APIDOX in New Code ==

== Writing APIDOX in New Code ==

 

The following little checklist should get you through the worst of writing apidox.  

The following little checklist should get you through the worst of writing apidox.  

'''1. Write apidox as you code'''

'''1. Write apidox as you code.'''

The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.

The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.

This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.  

This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.  

'''2. Document your modules completely'''

'''2. Document your packages completely'''

Modules 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 module 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 module should have a module-level comment.  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 package should have a package comment.   

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

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

   The Ungulate methods collects classes and methods

  <nowiki>"""</nowiki>

  pertaining to hooved animals.

   Here is the description of the package named sugar.

   """

   <nowiki>"""</nowiki>

 

   namespace Ungulate {

   //DOXYGEN_EXCLUDE

</code>

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

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.

<code>

<code>

   """

   <nowiki>"""</nowiki>

   The Ungulate namespace collects classes and methods

   @mainpage Control Panel

   pertaining to hooved animals.

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

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

 

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

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.

-->

-->