Just like in JavaDoc, the documentation for DOC++ is contained in special versions of Java, C or C++ comments. These are comments with the format:
- /** ... */
- /// ...
Note that DOC++ comments are only those with a double asterisk `/**' or `//' respectively. 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 in documentation provided in the DOC++ comment and some information from the subsequent declaration, if available.
Trailing comments can be used to define manual entries too by turning on the Quantel extensions. This is done by using the `--quantel' (or `-Q') command line option.
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 args DOC++ depends on source code author user author deprecated user doc for deprecated functions doc user long documentation exception user doc for exceptions thrown by a function field user doc for fields documentation friends DOC++ doc for entry's friends invariant user doc for invariants memo user short documentation name both depends on source code param user doc of parameters of a function postcondition user doc for postconditions precondition user doc for preconditions return user doc of return value of a function see user cross reference since user version since the function exists type DOC++ depends on source code version user version
Except for explicit 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 Snoopy
is used to fill the `@author' field with the text ``Snoopy''.
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 `@type', `@args' and `@doc' fields may not be filled explicitly.
Alphabetic index Hierarchy of classes