• Introduction
• Documentation specification
• Defined fields and their attributes
• Class hierarchy
• Source code documentation
• Module interface documentation

There are two types of fields: containers and attribute. Containers describe Pike language "objects" like a function, variable, class etc. or structural source code elements like a file or module. Attribute fields are the given object's description properties. The container fields must always appear before the attribute fields they contain! The attribute fields available for the given container have to (if they appear) be in the same comment as their container.
Descriptions are organized in a tree structure resembling the Pike code lexical structure - the variables, methods and classes belong in files where they are defined. This allows for documenting objects with the same names but defined in different files.
As Caudium is extensible through the use of modules a separate container to describe the public interface and task of the given module is also provided. Keep in mind that the Caudium module is different to Pike module and its description has a different purpose than that of the source code methods, variables and classes although certain elements appear (or may appear) in both descriptions. Generally, the rule is that the source (Pike) code descriptions are intended for the developer documentation, while the module descriptions are meant for the user/administrator of the Caudium server. For that reason the documentation parser generates two sets of documentation - one containing all the source code documentation and the other containing only the Caudium module documentation.

The general format of the inline Caudium documentation is as follows:

/*
**|
**| field_name: field contents
**|  field_contents
**|  .
**|  field_contents
*/

or

//|
//| field_name: field contents
//|  field_contents
//|  .
//|  field_contents

The documentation extraction program parses C and C++ comments formatted as shown above. If the continuation lines of a comment have no the <asterisk><asterisk><pipe> or <slash><slash><pipe> form then they are not treated as extractable documentation block. The **| or //| block is ignored and the following character is treated as the first column of the actual documentation page. Think of **| or //| as your gutter or margin :).
field_name must be separated from the comment chars (**|) with at least one horizontal whitespace character (tab or space). field_contents must have at least one more horizontal whitespace character to be treated as the contents of the field. If this is not the case, the line will be treated as the next field label, possibly causing a parser error. The only exception to this rule is an empty line - that is line containing only horizontal whitespace or just a newline (except for the **| string, of course)
field_contents may contain any valid HTML markup as well as the Caudium-specific XML markup (*fixme* - define the markup :-)). Keep in mind, however, that both kinds of markup must follow the XML syntax - the attribute names are case-sensitive, the attribute values must be enclosed in single or double quotes, the closing tag is always required. If the parser encounters a string enclosed in single quotes being not the markup attribute value, such string is treated as a reference to a function/variable/constant described elsewhere in the documentation (the string in quotes must match that of the name: field of the relevant function) and will be replaced by a reference to that description.
field_contents may also contain a simplified bullet list construct. Every list item must be indented at least as much as the field body but must start with the '-' (dash) character followed by the body of the item.The body must be indented to the same column as the first non-whitespace character following the starting dash. If you want to embed an empty line in the item body, you must put a single '.' (dot) character as the sole content of the line. An example:

/*
**| method: int foo(void);
**|  Field contents starts here - indented with one space more than the label above.
**|
**|  The above line is a part of the field contents. Below is a list:
**|
**|   - ITEM - item description. It may span several
**|     lines. Note the 'l' at the start of this line is below 'I' above.
**|     .
**|     The dot above introduces an empty line in the item description.
**|
**|   - NEXT ITEM - next item is described here.
*/

Below you will find a description of all recognized documentation fields. Each container field is described in a separate table. Some fields take a set of predefined values while the other fields have textual contents. The former fields may have a default value which is marked in the Value column with bold text. The word none means that the given field has no default value. The Type column can contain the following combinations of symbols:

• C - the field is a container
• CT - the field is a top-level container
• T - the field is an attribute
• TR - the field is a required attribute

Class hierarchy

Source code documentation

Module interface documentation