Structured comments appearing before C data structures have the following general format:
/* @dataPointerName********************************************** ** **DatatypeDescription**DatatypeDescription cont.** ** @aliasStructName** @aliasObjectName** ** @newDescription** @deleteDescription** @assignDescription** ** @attrElement1[Datatype1]Description** @attrElement2[Datatype2]Description** ** @@ **Comments**Comments cont.** *******************************************************************/ typedef structStructName{Datatype1Element1;Datatype2Element2; }ObjectName#definePointerNameObjectName*
Where:
PointerName is the pointer datatype, e.g. AjPStr.
StructName is the structure name, e.g. AjSStr.
ObjectName is the object datatype e.g. AjOStr.
DatatypeDescription is a description of the datatype that appears in the online documentation. It may span multiple lines.
Element* is a variable name of an element of the structure.
Datatype* is the datatype of an element of the structure.
Description is a description of an element of the structure or of a function that operates on it (see below for use of tags).
Comments are optional comments that will not appear in the online documentation.
In the example below there is an additional pointer datatype (AjPPStr). This is not required for most datatypes:
/* @data AjPStr ***************************************************************
**
** Ajax string object.
**
** Holds a null terminated character string with additional data.
** The length is known and held internally.
** The reserved memory size is known and held internally.
** The reference count is known and held internally.
** New pointers can refer to the same string without needing
** to duplicate the character data.
**
** If a string has multiple references it cannot be changed. Any
** instance to be changed is first copied to a new string. This
** means that any function which can change the character data must
** pass a pointer to the string so that the string can be moved.
**
** A default null string is provided. New strings are by default
** implemented as pointers to this with increased reference counters.
**
** AjPStr is implemented as a pointer to a C data structure.
**
** @alias AjPPStr
** @alias AjSStr
** @alias AjOStr
** @iterator AjIStr
**
** @attr Res [ajuint] Reserved bytes (usable for expanding in place)
** @attr Len [ajuint] Length of current string, excluding NULL at end
** @attr Ptr [char*] The string, as a NULL-terminated C string.
** @attr Use [ajuint] Use count: 1 for single reference, more if several
** pointers share the same string.
** Must drop to 0 before deleting. Modifying means making
** a new string if not 1.
** @attr Padding [ajint] Padding to alignment boundary
** @@
******************************************************************************/
typedef struct AjSStr
{
ajuint Res;
ajuint Len;
char *Ptr;
ajuint Use;
ajint Padding;
} AjOStr;
#define AjPStr AjOStr*
typedef AjPStr* AjPPStr;The available tags are preceded by @. Some of the tags (Table D.2, “Datatype Documentation Tags”) refer to functions which act upon the data structure.
| Tag | Description |
|---|---|
@data | Start of structured comment. Gives the datatype for the pointer to the data structure (e.g. AjPStr) and is followed by any number of lines of free text with markup. Use @datastatic if the data structure is not publicly visible. |
@datastatic | Same as @data, but for static (internal) datatypes. |
@alias | Aliases for related datatypes and names. The standard practice is to use the pointer name (AjPStr etc.) as the main name, and the object name (AjOStr etc.) and the structure name (AjSStr etc.) as aliases. These are used to markup references through aliases in the source code. |
@iterator | Name of the iterator datatype (e.g. AjIStr), if any, associated with this datatype. |
@other | Name of any other datatype associated with this datatype |
@new | Constructor. Gives the function name, followed by a copy of the function description. |
@delete | Destructor. Gives the function name, followed by a copy of the function description. |
@assign | Assignment (overwrites the value). Gives the function name, followed by a copy of the function description. |
@modify | Modifier (updates the value). Gives the function name, followed by a copy of the function description. |
@cast | Casts the value into something else as the return type or another parameter. Gives the function name, followed by a copy of the function description. |
@use | Uses the value but does not modify it or return any part. Gives the function name, followed by a copy of the function description. |
@input | Input function (reads an input source and populates the datatype). Gives the function name, followed by a copy of the function description. |
@output | Output function (writes the values to an output file). Gives the function name, followed by a copy of the function description. |
@iterate | Iteration function (iterates over value or array of values). Gives the function name, followed by a copy of the function description. |
@attr | Attribute name, type and description. Attributes are defined in the same order as they appear in the structure. The name and type must match the true definition. |
@cc | Comment inserted between groups of attributes. No comments are allowed in the structure itself (to provide clean parsing) so comments are inserted in the header. |