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

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 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 */, where the < denotes that the documentation applies to the thing just past.It looks like this:

enum State {

none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */

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.

APIDOX in altem Code korrigieren

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.

Beispiel 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. Doxygen does not require a strict style -- it 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 <degroot@kde.org>
* @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.

Broken parameter documentation: Documenting parameters to methods can be done two ways: you can document none of them, or you can document
all of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document all of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
/** Calculate the root-mean-square distance from the

* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document none of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
/** Calculate the root-mean-square distance from the origin to

* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/

double distance(int x, int y, bool nonFree=false);

Misuse of tags in running text: This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

Chosing between Doxygen errors and compiler warnings: If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

Accidental tags: It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

Accidental HTML: If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
/** This method connects to a database. The connection string is

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:

Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.

Use the HTML formatting that Doxygen makes available, and write <i>foo</i> instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.

Superfluous @ref

It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.