home > resources > c++ coding standard > online version
Uwyn C++ Coding Standard
Prev Chapter 4. Class Design Next

Class Documentation

For the creation of developer API documentation we're using kdoc. Since we've selected a stripped down version of Qt as our class library it's a great asset that a documentation tool understands the concept of Qt's meta object system, slots and signals. Although this is only available in a more feature-packaged distribution of Qt, it's very probable that in the future, parts of portage will require these additional features and having support for them in the documentation tool is thus a great asset.

Kdoc is very much likely to javadoc, but then for c++.

A documentation comment is a C comment that immediately precedes a class, method, constant or property declaration. It takes the following form:

Example 4-5. Documentation Comment Example

/**
* Documentation goes here
*/
class MyClass
{
    ...

The double asterisk at the start of the comment differentiates a documentation comment from a normal comment. To make the documentation comment blocks clearly stand out, each line can be preceded by asterisks which will be ignored when the output is generated.

The documentation is a mixture of:

Normal text

Paragraphs must be separated by at least one blank line.

Code fragments

Inline code fragments have to take the following form :

Example 4-6. Documentation inlined code fragment example

<pre>
.....code fragments....
</pre>

Various kdoc tags

The tags that kdoc understand are all in the following form and should be entered on one line (@ref is an exception):

Example 4-7. The form of kdoc tags

@tagname [tag parameters]

List of KDoc valid tags

The valid KDoc tags for each type of source code entity are:

Table 4-1. List of valid tags

Classes
@short [one_sentence] A short description of the class.
@author [one_sentence] The class's author.
@version [once_sentence] The class's version. This can for example be set to the RCS/CVS tag $Id.
@see [references_to_classes_or_methods] References to other related documentation.
Methods
@see as above
@return [one_sentence] A sentence describing the return value.
@exception [exceptions] List the exceptions that could be thrown by this method.
@param [param_name] [param_description] Describe a parameter. The param description can span multiple lines and will be terminated by a blank line, the end of the comment, or another param entry. For this reason, param entries should normally be the last part of the doc comment.
Constants, Enums, Properties
@see as above
ANYWHERE
@ref As a departure from the javadoc format, the metatag @ref has the same format as @see, but can appear anywhere in the documentation (all other tags must appear on a line by themselves).
Prev Home Next
Accessor Styles Up Language Directives and Best Practices