Caudium Inline Documentation Specification

# Table of contents

- Introduction
- Documentation specification
- Defined fields and their attributes

- Class hierarchy
- Source code documentation
- Module interface documentation

# Introduction

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.

# Documentation specification

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.
>     */

# Defined fields and their attributes

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

Here is the "class hierarchy" tree with links to element definitions:

    file
        cvs_version
        method
    	name
    	scope
    	arg
    	returns
    	see also
    	note
    	example
    	fixme
        globvar
        class
    	scope
    	method
    	globvar
    	see also
    	example
    	fixme

    module
        cvs_version
        type
        provides
        variable
    	type
    	default
        tag
    	example
    	attribute
    	    default
    	returns
    	see also
    	note
        method
    	name
    	scope
    	arg
    	returns
    	see also
    	note
    	example
    	fixme

## Source code documentation

Field | Description | Value | Type | Contains
--- | --- | --- | --- | ---
file | Briefly documents the source file | file name (e.g. http.pike) in the first line and a file purpose description in the following lines. Each description line must start with at least one whitespace character (space, tab) | CT | cvs_version method globvar class
cvs_version | the CVS version of the file | The $Id: docspec.html,v 1.6 2001/01/23 09:35:44 wilsonm Exp $ string in most cases - replaced with the actual version by the CVS system | TR |

Field | Description | Value | Type | Contains
--- | --- | --- | --- | ---
method | Full description of a pike method | valid Pike method declaration in the first line, method description in the following lines. Each description line must start with at least one whitespace (space, tab) | CT | name scope arg returns see also note example fixme
name | method name followed by a short description. This field is used for generation of the "see also" links as well as the table of contents and indices. It contains only one line of text strictly in the format described in the Value column. | method_name - short description | TR |
scope | defines the visibility scope of the method | public | private | T |
arg | method argument description. This field must appear once for every method argument. | valid Pike argument declaration (type name) in the first line followed by the description lines. Each description line must start with at least one whitespace (space, tab). | T |
returns | description of the method return value. If omitted, the method is assumed to return void | valid Pike type declaration in the first line followed by the description lines. Each description line must start with at least one whitespace (space, tab). | T |
see also | any directions and comments on further documentation related to this method but found elsewhere. Can contain embedded links to other methods/files/classes/variables/modules. | free text with embedded links. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | T |
note | additional notes about the method | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | T |
example | a commented example of the function usage | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | T |
fixme | notes about known bugs/errors/limitations of the method that are planned to be fixed by the maintainer | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | T |

Field | Description | Value | Type | Contains
--- | --- | --- | --- | ---
globvar | Full description of a pike variable | valid Pike variable declaration in the first line, variable description in the following lines. Each description line must start with at least one whitespace (space, tab) | C |

Field | Description | Value | Type | Contains
--- | --- | --- | --- | ---
class | Full description of a pike class | valid Pike class name in the first line, class description in the following lines. Each description line must start with at least one whitespace (space, tab) | C | scope method globvar see also note example fixme

## Module interface documentation

Field | Description | Value | Type | Contains
--- | --- | --- | --- | ---
module | Briefly documents the Caudium module. Unlike the file container, module has to be described in one comment block. | module name as seen in the configuration interface | CT | cvs_version type provides variable tag method
type | Caudium module type | One or more of the Caudium module type constants | TR |
provides | If the module is a provider, a description of what it provides | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | T |

Field | Description | Value | Type | Contains
--- | --- | --- | --- | ---
variable | describes a variable exported by the module | variable name in the first line, variable description in the following lines. Each description line must start with at least one whitespace (space, tab) | C | type default
type | variable type | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | TR |
default | default value of the variable | free text. One line only. | TR |

Field | Description | Value | Type | Contains
--- | --- | --- | --- | ---
tag | describes a tag defined by the module | tag name in the first line, tag description in the following lines. Each description line must start with at least one whitespace (space, tab) | C | example attribute returns see also note
example | tag usage example demonstrating all attributes | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | T |
returns | return value of the tag with possible side effects | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | TR |
see also | related tags and information | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | T |
note | additional notes and comments on the tag and its usage | free text. Each line except for the one immediately following the colon must start with at least one whitespace (space, tab) | T |

Field | Description | Value | Type | Contains
--- | --- | --- | --- | ---
attribute | describes a tag attribute | attribute name in the first line, attribute description in the following lines. Each description line must start with at least one whitespace (space, tab) | C | default
default | default value of the attribute | free text. One line only | T |

Copyright © 2000 The Caudium Group

> $Id: docspec.html,v 1.6 2001/01/23 09:35:44 wilsonm Exp $