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

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