Cleanup optional argument headers (#5543)

addons/captives/functions/fnc_canStopEscorting.sqf

@@ -1,13 +1,13 @@
 /*
  * Author: PabstMirror
- * Tests if player can stop escorting
+ * Tests if player can stop escorting.
  *
  * Arguments:
- * 0: caller (player) <OBJECT>
+ * 0: Caller (player) <OBJECT>
- * 1: target <OBJECT><OPTIONAL>
+ * 1: Target <OBJECT> (default: objNull)
  *
  * Return Value:
- * The return value <BOOL>
+ * Can unit stop escorting another unit <BOOL>
  *
  * Example:
  * [player, bob] call ACE_captives_fnc_canStopEscorting

addons/cargo/functions/fnc_canUnloadItem.sqf

@@ -5,7 +5,7 @@
  * Arguments:
  * 0: loaded Object <OBJECT>
  * 1: Object <OBJECT>
- * 2: Unloader (player) <OPTIONAL><OBJECT>
+ * 2: Unloader (player) <OBJECT> (default: objNull)
  *
  * Return Value:
  * Can be unloaded <BOOL>

addons/chemlights/functions/fnc_throwIR.sqf

@@ -5,13 +5,13 @@
  * Arguments:
  * 0: Original throw projectile <OBJECT>
  * 1: Class of projectile <STRING>
- * 2: Adv throw (default: false) <BOOL><OPTIONAL>
+ * 2: Adv throw <BOOL> (default: false)
  *
  * Return Value:
  * None
  *
  * Example:
- * [_projectile, _ammoType] call ace_chemlights_fnc_throwIR;
+ * [_projectile, _ammoType] call ace_chemlights_fnc_throwIR
  *
  * Public: No
  */

addons/common/functions/fnc_dumpArray.sqf

@@ -4,7 +4,7 @@
  *
  * Arguments:
  * 0: Array to be dumped <ARRAY>
- * 1: Depth <NUMBER><OPTIONAL>
+ * 1: Depth <NUMBER> (default: 0)
  *
  * Return Value:
  * None

addons/common/functions/fnc_findUnloadPosition.sqf

@@ -1,20 +1,20 @@
 /*
  * Author: PabstMirror, ViperMaul
- * Find a safe place near a vehicle to unload something
+ * Find a safe place near a vehicle to unload something.
- * Handles Normal Terrain, In Water or On Buildings (Pier, StaticShip)
+ * Handles Normal Terrain, In Water or On Buildings (Pier, StaticShip).
  *
  * Arguments:
  * 0: Source Vehicle <OBJECT>
  * 1: Cargo Classname <STRING>
- * 2: Unloader (player) <OBJECT><OPTIONAL>
+ * 2: Unloader (player) <OBJECT> (default: objNull)
- * 3: Max Distance (meters) <NUMBER><OPTIONAL>
+ * 3: Max Distance (meters) <NUMBER> (default: 10)
- * 4: Check Vehicle is Stable <BOOL><OPTIONAL>
+ * 4: Check Vehicle is Stable <BOOL> (default: true)
  *
  * Return Value:
- * Unload PositionAGL (Can Be [] if no valid pos found) <ARRAY>
+ * Unload PositionAGL (can Be [] if no valid pos found) <ARRAY>
  *
  * Example:
- * [theCar, "CAManBase", player, 10, true] call ace_common_fnc_findUnloadPosition;
+ * [theCar, "CAManBase", player, 10, true] call ace_common_fnc_findUnloadPosition
  *
  * Public: No
  */

addons/common/functions/fnc_showHud.sqf

@@ -1,11 +1,11 @@
 /*
  * Author: PabstMirror
- * Allows multiple sources to not overwrite showHud command
+ * Allows multiple sources to not overwrite showHud command.
- * Bitwise AND Logic (a single false in a mask will make it false)
+ * Bitwise AND Logic (a single false in a mask will make it false).
  *
  * Arguments:
- * 0: Source ID <STRING><OPTIONAL>
+ * 0: Source ID <STRING> (default: "")
- * 1: Show Hud Bool Array (8 to set, empty to remove) <ARRAY><OPTIONAL>
+ * 1: Show Hud Bool Array (8 to set, empty to remove) <ARRAY> (default: [])
  * - [hud, info, radar, compass, direction, menu, group, cursors]
  * - hud: Boolean - show scripted HUD (same as normal showHUD true/false)
  * - info: Boolean - show vehicle + soldier info (hides weapon info from the HUD as well)

addons/common/functions/fnc_unloadPersonLocal.sqf

@@ -3,12 +3,12 @@
  * Unload a person from a vehicle, local
  *
  * Arguments:
- * 0: unit to unload <OBJECT>
+ * 0: Unit to unload <OBJECT>
  * 1: Vehicle <OBJECT>
- * 2: Unloader (player) <OBJECT><OPTIONAL>
+ * 2: Unloader (player) <OBJECT> (default: objNull)
  *
  * Return Value:
- * Returns true if succesfully unloaded person <BOOL>
+ * Succesfully unloaded person <BOOL>
  *
  * Example:
  * [bob, car, bob] call ace_common_fnc_unloadpersonLocal

addons/common/functions/fnc_watchVariable.sqf

@@ -1,27 +1,27 @@
 /*
  * Author: PabstMirror
- * Shows multiple watched variables on the main display (for easy debugging)
+ * Shows multiple watched variables on the main display (for easy debugging).
  *
  * Arguments:
- * 0: Title (var name) <STRING>
+ * 0: Title (var name) <STRING> (default: "")
- * 1: Code to generate result (passed nothing, can return any) <OPTIONAL><CODE>
+ * 1: Code to generate result (passed nothing, can return any) <CODE> (default: {})
- * 2: Array containing modifiers <OPTIONAL><ARRAY>
+ * 2: Array containing modifiers <ARRAY> (default: [])
  * For Numbers:
- *      0: Show Delta change (default: true) <OPTIONAL><BOOL>
+ *      0: Show Delta change <BOOL> (default: true)
- *      1: Slider Min Value (default: 0) <OPTIONAL><NUMBER>
+ *      1: Slider Min Value <NUMBER> (default: 0)
- *      1: Slider Max Value (default: 0) <OPTIONAL><NUMBER>
+ *      1: Slider Max Value <NUMBER> (default: 0)
  * For Anything else:
- *      0: Number of structured text lines (default: 1) <OPTIONAL><NUMBER>
+ *      0: Number of structured text lines <NUMBER> (default: 1)
  *
  * Return Value:
  * None
  *
  * Example:
- * ["CBA_missionTime"] call ace_common_fnc_watchVariable; // Uses title as code
+ * ["CBA_missionTime"] call ace_common_fnc_watchVariable // Uses title as code
- * ["diag_frameNo", {diag_frameNo}, [false]] call ace_common_fnc_watchVariable; // Won't show delta
+ * ["diag_frameNo", {diag_frameNo}, [false]] call ace_common_fnc_watchVariable // Won't show delta
- * ["blood", {player getVariable "ace_medical_bloodVolume"}, [true, 0, 100]] call ace_common_fnc_watchVariable; // Shows slider
+ * ["blood", {player getVariable "ace_medical_bloodVolume"}, [true, 0, 100]] call ace_common_fnc_watchVariable // Shows slider
- * ["multiLine text", {"Line 1 <br/>Line 2"}, [2]] call ace_common_fnc_watchVariable;
+ * ["multiLine text", {"Line 1 <br/>Line 2"}, [2]] call ace_common_fnc_watchVariable
- * ["player names", {allPlayers apply {name _x}}, [5]] call ace_common_fnc_watchVariable; // handles any data types
+ * ["player names", {allPlayers apply {name _x}}, [5]] call ace_common_fnc_watchVariable // handles any data types
  *
  * Public: Yes
  */

addons/disarming/functions/fnc_disarmDropItems.sqf

@@ -4,10 +4,10 @@
  * Makes a unit drop items
  *
  * Arguments:
- * 0: caller (player) <OBJECT>
+ * 0: Caller (player) <OBJECT>
- * 1: target <OBJECT>
+ * 1: Target <OBJECT>
- * 2: classnamess <ARRAY>
+ * 2: Classnames <ARRAY>
- * 3: Do Not Drop Ammo <BOOL><OPTIONAL>
+ * 3: Do Not Drop Ammo <BOOL> (default: false)
  *
  * Return Value:
  * None

addons/explosives/functions/fnc_placeExplosive.sqf

@@ -1,6 +1,6 @@
 /*
  * Author: Garth 'L-H' de Wet
- * Places an explosive at the requested position
+ * Places an explosive at the requested position.
  *
  * Arguments:
  * 0: Unit <OBJECT>
@@ -9,14 +9,13 @@
  * 3: Magazine class <STRING>
  * 4: Config of trigger <STRING>
  * 5: Variables required for the trigger type <ARRAY>
- * 6: Explosive placeholder <OBJECT> <OPTIONAL>
+ * 6: Explosive placeholder <OBJECT> (default: objNull)
  *
  * Return Value:
  * Placed explosive <OBJECT>
  *
  * Example:
- * _explosive = [player, player modelToWorldVisual [0,0.5, 0.1], 134,
+ * _explosive = [player, player modelToWorldVisual [0,0.5, 0.1], 134, "SatchelCharge_Remote_Mag", "Command", []] call ace_explosives_fnc_placeExplosive
- *  "SatchelCharge_Remote_Mag", "Command", []] call ACE_Explosives_fnc_placeExplosive;
  *
  * Public: Yes
  */

addons/explosives/functions/fnc_scriptedExplosive.sqf

@@ -1,19 +1,18 @@
 /*
  * Author: VKing
- * Detonate explosives via script, for use in triggers or mission scripts to
+ * Detonate explosives via script, for use in triggers or mission scripts to detonate editor-placed explosives.
- * detonate editor-placed explosives.
  *
  * Arguments:
  * 0: Explosives objects to detonate <OBJECT or ARRAY>
- * 1: Fuze delay (for each explosive; use negative number for random time up to value) <NUMBER> <OPTIONAL>
+ * 1: Fuze delay (for each explosive; use negative number for random time up to value) <NUMBER> (default: 0)
- * 2: Trigger Item Classname <STRING><OPTIONAL>
+ * 2: Trigger Item Classname <STRING> (default: "#scripted")
  *
  * Return Value:
  * None
  *
  * Example:
- * [[charge1, charge2, charge3], -1] call ACE_Explosives_fnc_scriptedExplosive;
+ * [[charge1, charge2, charge3], -1] call ace_explosives_fnc_scriptedExplosive
- * [[claymore1, claymore2]] call ACE_Explosives_fnc_scriptedExplosive;
+ * [[claymore1, claymore2]] call ace_explosives_fnc_scriptedExplosive
  *
  * Public: Yes
  */

addons/explosives/functions/fnc_startTimer.sqf

@@ -5,13 +5,13 @@
  * Arguments:
  * 0: Explosive <OBJECT>
  * 1: Time till detonate <NUMBER>
- * 2: Trigger Item Classname <STRING><OPTIONAL>
+ * 2: Trigger Item Classname <STRING> (default: "#timer")
  *
  * Return Value:
  * None
  *
  * Example:
- * [_explosive, 10] call ACE_Explosives_fnc_startTimer;
+ * [_explosive, 10] call ace_explosives_fnc_startTimer
  *
  * Public: Yes
  */

addons/hearing/functions/fnc_updateVolume.sqf

@@ -1,10 +1,10 @@
 /*
  * Author: commy2 and esteldunedain and Ruthberg
- * Updates and applys the current deafness.  Called every 1 sec from a PFEH.
+ * Updates and applies the current deafness. Called every 1 sec from a PFEH.
  *
  * Arguments:
  * 0: Args <ARRAY>
- * -----0: Just update volume (skip ringing/recovery) <BOOL><OPTIONAL>
+ *   0: Just update volume (skip ringing/recovery) <BOOL> (default: false)
  *
  * Return Value:
  * None
@@ -22,7 +22,7 @@ if (!alive ACE_player) exitWith {
     [QUOTE(ADDON), 1, true] call EFUNC(common,setHearingCapability);
 };
 
-(_this select 0) params ["_justUpdateVolume"];
+(_this select 0) params [["_justUpdateVolume", false]];
 
 GVAR(deafnessDV) = (GVAR(deafnessDV) min 20) max 0;
 GVAR(volume) = (1 -  (GVAR(deafnessDV) / 20)) max 0.05;

addons/interact_menu/functions/fnc_handleEscapeMenu.sqf

@@ -3,10 +3,13 @@
  * Handle the escape key being pressed.
  *
  * Arguments:
- * 0: Escape menu display that should be closed <DISPLAY><OPTIONAL>
+ * 0: Escape menu display that should be closed <DISPLAY> (default: displayNull)
  *
  * Return Value:
- * Nothing
+ * None
+ *
+ * Example:
+ * [display] call ace_interact_menu_fnc_handleEscapeMenu
  *
  * Public: No
  */

addons/interaction/functions/fnc_showMouseHint.sqf

@@ -1,12 +1,12 @@
 /*
  * Author: Garth de Wet (LH)
- * Shows the interaction helper text with the mouse buttons at the bottom middle of the screen
+ * Shows the interaction helper text with the mouse buttons at the bottom middle of the screen.
  *
  * Arguments:
  * 0: Left Click Text <STRING>
  * 1: Right Click Text <STRING>
- * 2: Scroll Text <STRING> (Optional)
+ * 2: Scroll Text <STRING> (default: "")
- * 2: Extra Icon/Text pairs <OPTIONAL><ARRAY>
+ * 2: Extra Icon/Text pairs <ARRAY> (default: [])
  *
  * Return Value:
  * None

addons/laser/functions/fnc_laserOn.sqf

@@ -8,15 +8,15 @@
  * 2: Method, can be code, which emitter and owner are passed to, a string function name, an array with a position memory point and weapon name, or an array with a position memory point, a vector begining memory point, and vector ending memory point. <STRING><CODE><ARRAY>
  * 3: Wavelength (1550nm is common eye safe) <NUMBER>
  * 4: Laser code <NUMBER>
- * 5: Beam divergence (in mils off beam center). <NUMBER>
+ * 5: Beam divergence (in mils off beam center) <NUMBER>
- * 6: Method Args <OPTIONAL><ANY>
+ * 6: Method Args <ANY> (default: nil)
  *
  * Return Value:
- * UUID for sending to laserOff function. <String>
+ * UUID for sending to laserOff function <STRING>
  *
  * Example:
- * [hmg, hmg, [[0,0,1], "HMG_static"], 1550, 1111, 1] call ace_laser_fnc_laserOn;
+ * [hmg, hmg, [[0,0,1], "HMG_static"], 1550, 1111, 1] call ace_laser_fnc_laserOn
- * [player, player, "ace_laser_fnc_findLaserSource", 1550, 1111, 1, ["pilot"]] call ace_laser_fnc_laserOn;
+ * [player, player, "ace_laser_fnc_findLaserSource", 1550, 1111, 1, ["pilot"]] call ace_laser_fnc_laserOn
  *
  * Public: No
  */

addons/laser/functions/fnc_seekerFindLaserSpot.sqf

@@ -8,15 +8,15 @@
  * 1: Direction vector (will be normalized) <ARRAY>
  * 2: Seeker FOV in degrees <NUMBER>
  * 3: Seeker max distance in meters <NUMBER>
- * 4: Seeker wavelength sensitivity range, [1550,1550] is common eye safe. <ARRAY>
+ * 4: Seeker wavelength sensitivity range, [1550,1550] is common eye safe <ARRAY>
  * 5: Seeker laser code. <NUMBER>
- * 6: Ignore 1 (e.g. Player's vehicle) <OPTIONAL><OBJECT>
+ * 6: Ignore 1 (e.g. Player's vehicle) <OBJECT> (default: objNull)
  *
  * Return Value:
- * [Strongest compatible laser spot ASL pos, owner object] Nil array values if nothing found. <ARRAY>
+ * [Strongest compatible laser spot ASL pos, owner object] Nil array values if nothing found <ARRAY>
  *
  * Example:
- * [getPosASL player, [0,1,0], 90, [1500, 1500], 1111, player] call ace_laser_fnc_seekerFindLaserSpot;
+ * [getPosASL player, [0,1,0], 90, [1500, 1500], 1111, player] call ace_laser_fnc_seekerFindLaserSpot
  *
  * Public: No
  */

addons/laser/functions/fnc_shootCone.sqf

@@ -1,19 +1,19 @@
 /*
  * Author: Nou
- * Shoots multiple rays in a dispersion pattern
+ * Shoots multiple rays in a dispersion pattern.
  *
  * Arguments:
  * 0: Origin position ASL <ARRAY>
  * 1: Direction (normalized) <ARRAY>
- * 2: Divergence (mils) <OPTIONAL><NUMBER>
+ * 2: Divergence (mils) <NUMBER> (default: 0.3)
- * 3: Count at each divergence level <OPTIONAL><NUMBER>
+ * 3: Count at each divergence level <NUMBER> (default: 3)
- * 4: Ignore vehicle 1 (e.g. Player's vehicle) <OPTIONAL><OBJECT>
+ * 4: Ignore vehicle 1 (e.g. Player's vehicle) <OBJECT> (default: objNull)
  *
  * Return Value:
  * [_longestReturn, _shortestReturn, _resultPositions] <ARRAY>
  *
  * Example:
- * [getPosASL player, [0,1,0]] call ace_laser_fnc_shootCone;
+ * [getPosASL player, [0,1,0]] call ace_laser_fnc_shootCone
  *
  * Public: No
  */

addons/laser/functions/fnc_shootRay.sqf

@@ -1,18 +1,18 @@
 /*
  * Author: Nou, PabstMirror
- * Shoots a ray from a source to a direction and finds first intersction and distance
+ * Shoots a ray from a source to a direction and finds first intersction and distance.
  *
  * Arguments:
  * 0: Origin position ASL <ARRAY>
  * 1: Direction (normalized) <ARRAY>
- * 2: Ignore 1 (e.g. Player's vehicle) <OPTIONAL><OBJECT>
+ * 2: Ignore 1 (e.g. Player's vehicle) <OBJECT> (default: objNull)
- * 2: Ignore 2 (e.g. Player's vehicle) <OPTIONAL><OBJECT>
+ * 2: Ignore 2 (e.g. Player's vehicle) <OBJECT> (default: objNull)
  *
  * Return Value:
  * [posASL, distance] - pos will be nil if no intersection <ARRAY>
  *
  * Example:
- * [getPosASL player, [0,1,0], player] call ace_laser_fnc_shootRay;
+ * [getPosASL player, [0,1,0], player] call ace_laser_fnc_shootRay
  *
  * Public: No
  */

addons/microdagr/functions/fnc_openDisplay.sqf

@@ -1,9 +1,9 @@
 /*
  * Author: PabstMirror
- * Changes the display mode of the microDAGR
+ * Changes the display mode of the MicroDAGR.
  *
  * Arguments:
- * 0: Display Mode to show the microDAGR in <NUMBER><OPTIONAL>
+ * 0: Display Mode to show the microDAGR in <NUMBER> (default: -1)
  *
  * Return Value:
  * None

addons/mk6mortar/functions/fnc_loadMagazineTimer.sqf

@@ -1,12 +1,12 @@
 /*
  * Author: Grey
- * Loads Magazine into static weapon using a timer
+ * Loads Magazine into static weapon using a timer.
  *
  * Arguments:
- * 0: static <OBJECT>
+ * 0: Static <OBJECT>
- * 1: unit <OBJECT>
+ * 1: Unit <OBJECT>
- * 2: time to load <NUMBER>
+ * 2: Time to load <NUMBER>
- * 3: magazineClassOptional <OPTIONAL><STRING>
+ * 3: Magazine Class <STRING> (default: "")
  *
  * Return Value:
  * None
@@ -20,7 +20,7 @@
 
 params ["_static","_unit","_timeToLoad",["_magazineClassOptional","",[""]]];
 
-//Move player into animation if player is standing
+// Move player into animation if player is standing
 if ((_unit call CBA_fnc_getUnitAnim) select 0 == "stand") then {
     [_unit, "AmovPercMstpSrasWrflDnon_diary", 1] call EFUNC(common,doAnimation);
 };

addons/zeus/functions/fnc_showMessage.sqf

@@ -1,11 +1,11 @@
 /*
  * Author: 654wak654
- * Shows a zeus message through the BIS function, handles localization.
+ * Shows a Zeus message through the BIS function, handles localization.
  * If multiple args are given, they get formatted.
  *
  * Arguments:
- * 0: The message <STRING>
+ * 0: Message <STRING>
- * N: Anything <ANY><OPTIONAL>
+ * N: Anything <ANY> (default: nil)
  *
  * Return Value:
  * None