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 _array - Array of key-value pairs to create Hash from [Array, defaults to []] 2 _filter - Function to filter each element [Function] 3 _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 Function: TAG_fnc_name 3 4 Description: 5 6 Parameters: 7 8 Returns: 9 10 Examples: 11 (begin example) 12 13 (end) 14 15 Author: 16 17 ---------------------------------------------------------------------------- */

Example

1 /* ---------------------------------------------------------------------------- 2 Function: CBA_fnc_enslaveMortals 3 4 Description: 5 Exert domination over puny humans. 6 7 This does not always work, especially if the unit being dominated is 8 particularly compared to the one trying to dominate. Domination can be 9 absolute or relatively benign, depending on value of _killOnMisbehave. 10 11 * Consider calling <CBA_fnc_avoidSuperheroes> first. 12 * Use <CBA_fnc_createKryptonite> in case you draw unwanted attention. 13 * This function never works on Thursdays. No-one knows why. 14 15 Parameters: 16 _units - Units to enslave [Array of units] 17 _killOnMisbehave - True to make disobedient minions die. If false, then just smack them about a bit [Boolean, defaults to true] 18 19 Returns: 20 List of those units that have been successfully enslaved [Array of units] 21 22 Examples: 23 (begin example) 24 _enslaved = [spooner, [sickboy, kju], true] call CBA_fnc_enslaveMortals; 25 // _enslaved => [sickboy, kju] 26 27 _enslaved = [sickboy, [spooner]] call CBA_fnc_enslaveMortals; 28 // _enslaved => [] 29 (end) 30 31 Author: 32 Spooner 2009-01-05 33 ---------------------------------------------------------------------------- */