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:
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:
Paragraphs must be separated by at least one blank line.
Inline code fragments have to take the following form :
The tags that kdoc understand are all in the following form and should be entered on one line (@ref is an exception):
The valid KDoc tags for each type of source code entity are:
Table 4-1. List of valid tags
|@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.|
|@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|
|@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).|