Documenting SQF functions

All automatic documentation is generated via NaturalDocs.

Generating documentation.

Formatting

Place a header (which can be a /* */ or // style block) in the function source file, ideally at the top. All comments in the file will be read though, to prepare the documentation and comments do not have to be specially formatted to be read.

1
2
3
    _array - Array of key-value pairs to create Hash from [Array, defaults to []]
    _filter - Function to filter each element [Function]
    _inPlace - true to alter the array itself, rather than create a new one [Boolean, defaults to false]
1
// If you want to do something similar, consider using <CBA_fnc_tickle> instead.

Any other word followed by a colon can be used as a heading, though standardisation by using "Parameters", "Example:", "Examples:", "Limitations:","Returns:" is a good idea. Always put content on the line after the heading line. An empty line separates paragraphs.

For full details, see the NaturalDocs documentation.

Template

Paste this at the top of the function file. Remember that all information should be on the line after heading, except the function name after Function:.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/* ----------------------------------------------------------------------------
Function: TAG_fnc_name

Description:

Parameters:

Returns:

Examples:
    (begin example)

    (end)

Author:

---------------------------------------------------------------------------- */

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
/* ----------------------------------------------------------------------------
Function: CBA_fnc_enslaveMortals

Description:
    Exert domination over puny humans.

    This does not always work, especially if the unit being dominated is
    particularly compared to the one trying to dominate. Domination can be
    absolute or relatively benign, depending on value of _killOnMisbehave.

    * Consider calling <CBA_fnc_avoidSuperheroes> first.
    * Use <CBA_fnc_createKryptonite> in case you draw unwanted attention.
    * This function never works on Thursdays. No-one knows why.

Parameters:
    _units - Units to enslave [Array of units]
    _killOnMisbehave - True to make disobedient minions die. If false, then just smack them about a bit [Boolean, defaults to true]

Returns:
    List of those units that have been successfully enslaved [Array of units]

Examples:
    (begin example)
        _enslaved = [spooner, [sickboy, kju], true] call CBA_fnc_enslaveMortals;
        // _enslaved => [sickboy, kju]

        _enslaved = [sickboy, [spooner]] call CBA_fnc_enslaveMortals;
        // _enslaved => []
   (end)

Author:
    Spooner 2009-01-05
---------------------------------------------------------------------------- */