Development/Tutorials/API Documentation
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 documentation is sometimes called an API reference manual. It needn't just be a reference manual, though, there can be extensive additional material, like tutorials, histories, etc. In this page, we will refer to all the material that documents and explains the API of a piece of code as "apidox."
Good apidox take some effort to write -- but I would say less 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, in six months time) 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) C code.
Preamble
APIDOX are what make a program accessible to other contributors. They are not essential, mind you, but they certainly help a great deal for new people who show up and want to work on your code, or better yet, re-use it elsewhere with a minimum of modification.
Look at the Qt documentation to get a feeling of what good apidox are like. There is a consistency of style, a thoroughness which permeates all the documentation. It is possible to learn a lot about Qt just from reading the documentation. You do not necessarily need to run the tutorial programs or read the source code of the library to find out what a parameter flags does in some method of the library. It is all spelled out for you.
Writing apidox is a two-part process. One part is technical: you need to understand the code you are documenting -- or at least know what it is supposed to do and how it is meant to be used. The other part is plain discipline: apidox are most useful when they are exhaustive.
This document is going to try to prevent the apidox process from becoming exhausting, by giving straightforward tips about how to go about writing apidox. There are also the apidox policies, which are much much stricter, which provide measurable properties that apidox must adhere to. Glance at them now. When you come back, say "thank goodness it doesn't have to be like that."
APIDOX Basics
APIDOX are processed by the Doxygen documentation tool. This tool reads source code for your application (or library) and produces nicely formatted documentation from it. There is a good reference manual available -- but I hope to make it unnecessary to read, for basic use anyway.
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 special comments. These comments start with /** (slash, star, star) -- 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 /** and */, like this:
/** This method increases the sexyness of Kontact and should as such
* be called whenever possible (i.e. instead of having idle time, you
* might think of calling this method and helping Kontact gain even
* more popularity). You might even insert it into your own event
* loop to ensure it is called as often as possible. If these calls
* decrease the number of new features, it's still no problem to
* call it.
*/
void incSexyness(KInstance *instance);
For proper apidox, you need to document every "thing" in your program. "Things" here are directories, files, namespaces, classes, methods, enums, and member variables. You can actually leave out files and directories, and concentrate on the latter. Complete apidox looks something like this:
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
} ;
You can see here that each nesting level of "things" is documented with a comment -- the Callout #1namespace, the class and the method. Things that are private do not need apidox, but things that are protected do.
It is important to document each level of nesting, because if you leave one level out, Doxygen will ignore the documentation in inner nesting levels, and you will be left wondering where it has gone. For instance, if we leave out the class documentation, then the method documentation for Socket() will vanish as well. This is one of the common pitfalls to writing apidox.
If you just do this -- write an explanation for every part of your program -- then you're already a long way on the road to having complete apidox. Writing all those explanations makes your program more accessible to other developers -- and often shows you where the design or choice of names is sub-optimal. So it's a win for you both ways.
You can consult the list of supported tags for examples of more fancy apidox -- explaining parameters, for instance, and annotating the apidox with credits and examples. It's also worthwhile to take a look at the section on enabling apidox, but it's also fine to divide the work: you write the apidox themselves, and ask me (mailto:[email protected]) to enable apidox generation for your module. And I will.
Writing APIDOX in New Code
f you are writing new code and want to write apidox, use KDevelop. Really. Properly configured, it can automatically set up all the skeletons for apidox that you need, and what you do is write the descriptions. No messing with apidox commands.
If you're not in that fortunate position, the following little checklist should get you through the worst of writing apidox.
- 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.
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.
- Document your headers completely. The headers 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 headers as you go along. This means:
- Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.
- Every namespace should have a comment. A given namespace 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.
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 namespace should have a comment. A given namespace 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.
/** The Ungulate namespace 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).
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
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).
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).
- 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 enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
- Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive.
For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */ instead, where the < denotes that the documentation applies to the thing just past.
It looks like this:
- Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive.
enum State {
none /**< No bracket seen */,
bracket /**< Found a ( for grouping */,
squote /**< Found a single quote */,
dquote /**< Found double quotes */
} ;
- Watch this space! Watch the English Breakfast Network for the results of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.
- Write a main page for your application. This is usually done in a separate file 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.
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.)
In old apidox, you are more likely to suffer from the following symptoms:
- Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
- Missing method documentation.
- Missing class documentation.
- Documentation that has wandered off on its own and is attached to the wrong thing now.
The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.
The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.
Example APIDOX
So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. The boilerplate makes use of my own favorite comment style, but this is no requirement: Doxygen will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.
Documentation for a file. The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.
/** @file
- This file is part of AnApplication and defines
- classes Ungulate and Moose.
- @author Mostly by me
- /
Documentation for a namespace.
/**
- This namespace collects functions related to
- counting and enumeration of mammals and their limbs.
- /
Documentation for a class. Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special Authors section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.
/**
- This class represents a Moose in the woodland
- simulator. A single Moose object can be created,
- but it is more useful to instantiate Moose::Factory
- by calling Moose::factory(), and then calling spawn()
- for each new Moose, since that maintains the ecological
- balance far better.
- @author Adriaan de Groot <[email protected]>
- @since 3.5
- /
Method documentation. We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.
/**
- This method names a particular Moose and
- as a side effect sets whether or not
- the Moose is treated as a Reindeer.
- When @p santa is @c true, the name of
- the moose is set to the next of the available
- Reindeer (if possible).
- @param name name to assign to the Moose,
- which is only relevant if the moose
- is not a Reindeer.
- @param santa is this Moose assigned to Santa?
- if so, the name is irrelevant.
- @return @c true if naming the Moose succeeded
- @return @c false if naming the Moose failed. This
- only happens if the Moose is assigned
- to Santa duty but there are already
- eight named Reindeer.
- /
bool name(const QString &name, bool santa = false);
Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.