Manual Entries

Just like in JavaDoc the documentation for DOC++ is contained in special versions of Java, C or C++ comment. These are comments with the format:
	    /**
	       ...
	    * /
	
Note, that DOC++ comments are only those with a double asterisk /**. We shall refer to such a comment as a DOC++ comment. Each DOC++ comment is used to specify the documentation for the subsequent declaration (of a variable, class, etc.).

Every DOC++ comment defines a manual entry. A manual entry consists of the documentation provided in the DOC++ comment and some information from the subsequent declaration, if available.

Manual entries are structured into various fields. Some of them are automatically filled in by DOC++ while the others may be specified by the documentation writer. Here is the list of the fields of manual entries:

Field name provider description
@type DOC++ depends on source code
@name both depends on source code
@args DOC++ depends on source code
@memo user short documentation
@doc user long documentation
@return user doc of return value of a function
@param user doc of parameter of a function
@exception user doc for exepction thrown by a function
@see user cross reference
@author user author
@version user version

Except for explicite manual entries, the first three fields will generally be filled automatically by DOC++. How they are filled depends on the category of a manual entry, which is determined by the source code following a DOC++ comment. Generally they contain the entire signature of the subsequent declaration. The following table lists all categories of manual entries and how the fields are filled

Category @type @name @args
macro #define name [argument list]
variable Type name -
function/method Return type name arguments list [exceptions]
union/enum union/enum name -
class/struct class/struct name [derived classes]
interface interface name [extended interfaces]
In any case @name contains the name of the declaration to be documented. It will be included in the table of contents.

The remaining fields are filled from the text in the DOC++ comment. Except for the @doc and @memo field, the text for a field must be preceeded by the field name in the beginning of a line of the DOC++ comment. The subsequent text up to the next occurrence of a field name is used for the field. Field @name is an exception in that only the remaining text in the same line is used to fill the field. As an example

	    @author	Roland Wunderling and Malte Z\"ockler
	
is used to fill the @author field with the text ``Roland Wunderling and Malte Zöckler''.

Text that is not preceeded by a field name is used for the @doc field. The very first text in a DOC++ comment up to the first occurrence of character `.' is also copied to the @memo field. This may be overridden by explicitly specifying a @memo field. In this case also characters `.' are allowed.

The fields @type, @args and @doc may not be filled explicitely.

Alphabetic index Hierarchy of classes



This page was generated with the help of DOC++.