D.6. Function Documentation

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:

/* @func FunctionName **********************************************
**
** FunctionDescription
** FunctionDescription cont.
**
** @param [ParameterCode1] ParameterName1 [Datatype1] Description
** @param [ParameterCode2] ParameterName2 [Datatype2] Description
** @return [Datatype] Description
** @cre Description
** @ure Description
** @exception ExceptName Description 
** @see RelatedFunctionName
** @@
**
** Comments
** Comments cont.
** 
*******************************************************************/

Datatype FunctionName (Datatype ParameterName1, Datatype ParameterName2) 
{
    /* Function C code goes here */
}

Where:

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;
}

D.6.1. Function Documentation Tags

The available tags (Table D.3, “Function Documentation Tags”) are preceded by @ and are based on the set defined in JavaDoc.

Table D.3. Function Documentation Tags
TagDescription
@funcStart 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.
@funcstaticSame as @func, but for static (internal) functions.
@paramUsed 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).
@creDescription of checked runtime error(s) for a parameter.
@ureDescription of unchecked runtime error(s) for a parameter.
@returnDatatype and description of the return value for successful execution.
@errorDescription of the return value(s) for errors condition(s). Can be used more than once if appropriate.
@exceptionException(s) thrown by this function. Can be used more than once if appropriate.
@seeCross-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..

D.6.2. Parameter Codes

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.

Table D.4. Parameter Codes (basic types)
CodeMnemonicDescription
rReadParameter value is used but not changed in any way.
wWriteParameter value is ignored. A new value is always written unless specific conditions (which should be documented) apply.
uUpdateParameter value is used, and a new value is (typically) written.
dDeleteParameter value is a pointer to memory to be freed. The pointer will be set to NULL.
fPointer to functionParameter value is a pointer to a function. The description should indicate the function type.
vVarargParameter value is a variable-length argument list of some form.
Table D.5. Parameter Codes (modifiers)
CodeMnemonicDescription
CCheckedThe value is checked. See the @cre tag for checked runtime errors.
EEmptyAn empty value will be accepted, for example a string of length zero.
NNullA NULL value will be accepted
PPointerUse this if a pointer itself is potentially written to rather than just the data it points to.