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