## Manual Entries

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++.