Skip to content

Documenting SQF functions

Jump to bottom
Filip Maciejewski edited this page Jun 28, 2021 · 3 revisions

All automatic documentation is generated via NaturalDocs. See [generating documentation from SQF functions](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.

  • Function: <name> This should be the name of the function when it is compiled. Although this has to be entered by hand, it is checked to see if it is correct during the build process.
  • Description: The first paragraph after this heading will be used as the description for the Functions dialog.
  • (begin code) ... (end code) Preformatted code, such as you might want in examples.
  • A definition list, as used for listing parameters, is made simply with a - between value and definition.
    _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]
  • Bullet points by placing * at start of lines.
  • Cross-references are made with <> around the name of a function you wish to reference. E.g.
// 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:.

/* ----------------------------------------------------------------------------
Function: TAG_fnc_name

Description:

Parameters:

Returns:

Examples:
    (begin example)

    (end)

Author:

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

Example

/* ----------------------------------------------------------------------------
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
---------------------------------------------------------------------------- */
Clone this wiki locally