D.6. Function Documentation

D.6. Function Documentation
Prev	Appendix D. Code Documentation Standards	Next

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:

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

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

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)
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.

Table D.5. Parameter Codes (modifiers)
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.

Prev	Up	Next
D.5. Datatype Documentation	Home	Appendix E. Resources