Structured comments for static functions begin with @funcstatic
whereas exported functions are labelled @func
. For exported functions a prototype is declared in an associated header file. Structured comments before each function must have the following general format:
/* @funcFunctionName
********************************************** ** **FunctionDescription
**FunctionDescription cont.
** ** @param [ParameterCode1
]ParameterName1
[Datatype1
]Description
** @param [ParameterCode2
]ParameterName2
[Datatype2
]Description
** @return [Datatype
]Description
** @creDescription
** @ureDescription
** @exceptionExceptName
Description
** @seeRelatedFunctionName
** @@ ** **Comments
**Comments cont.
** *******************************************************************/Datatype
FunctionName
(Datatype
ParameterName1
,Datatype
ParameterName2
) { /* Function C code goes here */ }
Where:
FunctionName
is the name of the function.
FunctionDescription
is a description of the function that appears in the online documentation. It may span multiple lines.
ParameterCode*
is a parameter code (see below) describing a parameter and is followed by a short description of the parameter.
Datatype
is the datatype of a parameter or the datatype returned by the function (or void
for void functions).
RelatedFunctionName
is the name of a function related to the function in question.
Comments
are optional comments that will not appear in the online documentation.
For example:
/* @func ajStrMatchC ********************************************************** ** ** Simple test for matching a string and a text string. ** ** @param [r] str [const AjPStr] String ** @param [r] txt2 [const char*] Text ** @return [AjBool] ajTrue if two complete strings are the same ** @@ ******************************************************************************/ AjBool ajStrMatchC(const AjPStr str, const char* txt2) { if(!str || !txt2) return ajFalse; if(!strcmp(str->Ptr, txt2)) return ajTrue; return ajFalse; }
The available tags (Table D.3, “Function Documentation Tags”) are preceded by @
and are based on the set defined in JavaDoc.
Tag | Description |
---|---|
@func | Start of structured comment and followed by the function name and any number of lines of free text with markup. Use @funcstatic if the function is not publicly visible. |
@funcstatic | Same as @func , but for static (internal) functions. |
@param | Used once for each parameter. The parameter name (ParameterName ) and type (Datatype ) is as defined in the function. A parameter code (ParameterCode ) is also given (see below). |
@cre | Description of checked runtime error(s) for a parameter. |
@ure | Description of unchecked runtime error(s) for a parameter. |
@return | Datatype and description of the return value for successful execution. |
@error | Description of the return value(s) for errors condition(s). Can be used more than once if appropriate. |
@exception | Exception(s) thrown by this function. Can be used more than once if appropriate. |
@see | Cross-reference to related functions. A function name (RelatedFunctionName ) must be given that is identical to that given after the @func tag either in the same or a different source file. |
@@ | Effectively ends the structured comment. Any following text is ignored by the HTML conversion parser and will not appear in the online documentation.. |
The codes (Table D.4, “Parameter Codes (basic types)” and Table D.5, “Parameter Codes (modifiers)”) consists of lower case letter(s) for the basic type and upper case modifiers.
Code | Mnemonic | Description |
---|---|---|
r | Read | Parameter value is used but not changed in any way. |
w | Write | Parameter value is ignored. A new value is always written unless specific conditions (which should be documented) apply. |
u | Update | Parameter value is used, and a new value is (typically) written. |
d | Delete | Parameter value is a pointer to memory to be freed. The pointer will be set to NULL . |
f | Pointer to function | Parameter value is a pointer to a function. The description should indicate the function type. |
v | Vararg | Parameter value is a variable-length argument list of some form. |
Code | Mnemonic | Description |
---|---|---|
C | Checked | The value is checked. See the @cre tag for checked runtime errors. |
E | Empty | An empty value will be accepted, for example a string of length zero. |
N | Null | A NULL value will be accepted |
P | Pointer | Use this if a pointer itself is potentially written to rather than just the data it points to. |