Manual Entries


o Manual Entry Fields
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



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