Tools - document_functions.py: handle header sub indexs for arguments (#9303)

* tools - handle header sub indexs for arguements

* convert remaining

* Update coding-guidelines.md

addons/arsenal/functions/fnc_addSort.sqf

@@ -5,8 +5,8 @@
  *
  * Arguments:
  * 0: Tabs to add sort to <ARRAY>
- *   0.0: Left Tab Indexes <ARRAY of NUMBERS>
+ * - 0: Left Tab Indexes <ARRAY of NUMBERS>
- *   0.1: Right Tab Indexes <ARRAY of NUMBERS>
+ * - 1: Right Tab Indexes <ARRAY of NUMBERS>
  * 1: Sort Class (a unique string for each algorithm) <STRING>
  * 2: Title <STRING>
  * 3: Algorithm <CODE>

addons/arsenal/functions/fnc_addStat.sqf

@@ -5,18 +5,18 @@
  *
  * Arguments:
  * 0: Tabs to add the stat to <ARRAY of ARRAYS>
- *   0.0: Left tab indexes <ARRAY of NUMBERS>
+ * - 0: Left tab indexes <ARRAY of NUMBERS>
- *   0.1: Right tab indexes <ARRAY of NUMBERS>
+ * - 1: Right tab indexes <ARRAY of NUMBERS>
  * 1: Stat class (unique string for each stat) <STRING>
  * 2: Config entries to pass <ARRAY of STRINGS>
  * 3: Title <STRING>
  * 4: Show bar / show text bools <ARRAY of BOOLS>
- *   4.0: Show bar <BOOL> (default: false)
+ * - 0: Show bar <BOOL> (default: false)
- *   4.1: Show text <BOOL> (default: false)
+ * - 1: Show text <BOOL> (default: false)
  * 5: Array of statements <ARRAY of CODE>
- *   5.0: Bar code <CODE> (default: {})
+ * - 0: Bar code <CODE> (default: {})
- *   5.1: Text code <CODE> (default: {})
+ * - 1: Text code <CODE> (default: {})
- *   5.2: Condition code <CODE> (default: {true})
+ * - 2: Condition code <CODE> (default: {true})
  * 6: Priority <NUMBER> (default: 0)
  *
  * Return Value:

addons/arsenal/functions/fnc_handleMouse.sqf

@@ -8,9 +8,9 @@
  * Arguments:
  * 0: Not used
  * 1: Arguments <ARRAY>
-  * 1.0: Mouse area control <CONTROL>
+ * - 0: Mouse area control <CONTROL>
-  * 1.1: Mouse X position <NUMBER>
+ * - 1: Mouse X position <NUMBER>
-  * 1.2: Mouse Y position <NUMBER>
+ * - 2: Mouse Y position <NUMBER>
  *
  * Return Value:
  * None

addons/arsenal/functions/fnc_handleScrollWheel.sqf

@@ -6,8 +6,8 @@
  * Arguments:
  * 0: Not used
  * 1: onMouseZChanged EH return <ARRAY>
- *  1.0: Not used
+ * - 0: Not used
- *  1.1: Mousewheel Z position <NUMBER>
+ * - 1: Mousewheel Z position <NUMBER>
  *
  * Return Value:
  * None

addons/arsenal/functions/fnc_onArsenalClose.sqf

@@ -6,8 +6,8 @@
  * Arguments:
  * 0: Not used
  * 1: Args <ARRAY>
- *   1.0: Not used
+ * - 0: Not used
- *   1.1: Exit code <NUMBER>
+ * - 1: Exit code <NUMBER>
  *
  * Return Value:
  * None

addons/arsenal/functions/fnc_onArsenalOpen.sqf

@@ -7,7 +7,7 @@
  * Arguments:
  * 0: Not used
  * 1: Arguments <ARRAY>
- *  1.0: Arsenal display <DISPLAY>
+ * - 0: Arsenal display <DISPLAY>
  *
  * Return Value:
  * None

addons/arsenal/functions/fnc_onLoadoutsOpen.sqf

@@ -7,7 +7,7 @@
  * Arguments:
  * 0: Not used
  * 1: Arguments <ARRAY>
- *  1.0: Loadouts display <DISPLAY>
+ * - 0: Loadouts display <DISPLAY>
  *
  * Return Value:
  * None

addons/arsenal/functions/fnc_onMouseButtonDown.sqf

@@ -6,10 +6,10 @@
  * Arguments:
  * 0: Not used
  * 1: Args <ARRAY>
- *   1.0: Not used
+ * - 0: Not used
- *   1.1: Mouse button <NUMBER>
+ * - 1: Mouse button <NUMBER>
- *   1.2: Mouse X position <NUMBER>
+ * - 2: Mouse X position <NUMBER>
- *   1.3: Mouse Y position <NUMBER>
+ * - 3: Mouse Y position <NUMBER>
  *
  * Return Value:
  * None

addons/arsenal/functions/fnc_onMouseButtonUp.sqf

@@ -6,8 +6,8 @@
  * Arguments:
  * 0: Not used
  * 1: Args <ARRAY>
- *   1.0: Not used
+ * - 0: Not used
- *   1.1: Mouse button <NUMBER>
+ * - 1: Mouse button <NUMBER>
  *
  * Return Value:
  * None

addons/arsenal/functions/fnc_removeSort.sqf

@@ -10,8 +10,7 @@
  * None
  *
  * Example:
- *
+ * [["scopeSortL00", "scopeSortL01", "scopeSortL02", "scopeSortR07"]] call ace_arsenal_fnc_removeSort;
- [["scopeSortL00", "scopeSortL01", "scopeSortL02", "scopeSortR07"]] call ace_arsenal_fnc_removeSort;
  *
  * Public: Yes
 */

addons/arsenal/functions/fnc_statBarStatement_accuracy.sqf

@@ -7,8 +7,8 @@
  * 0: Not used
  * 1: Item config path <CONFIG>
  * 2: Args <ARRAY>
- *  2.0: Stat limits <ARRAY of BOOLS>
+ * - 0: Stat limits <ARRAY of BOOLS>
- *  2.1: Bar limits <ARRAY of NUMBERS>
+ * - 1: Bar limits <ARRAY of NUMBERS>
  *
  * Return Value:
  * <NUMBER>

addons/arsenal/functions/fnc_statBarStatement_default.sqf

@@ -7,9 +7,9 @@
  * 0: Stat <STRING>
  * 1: Item config path <CONFIG>
  * 2: Args for configExtreme <ARRAY>
- *  2.0: Stat limits <ARRAY of BOOLS>
+ * - 0: Stat limits <ARRAY of BOOLS>
- *  2.1: Bar limits <ARRAY of NUMBERS>
+ * - 1: Bar limits <ARRAY of NUMBERS>
- *  2.2: Evaluate as a logarithmic number <BOOL>
+ * - 2: Evaluate as a logarithmic number <BOOL>
  *
  * Return Value:
  * Bar statement <NUMBER>

addons/arsenal/functions/fnc_statBarStatement_impact.sqf

@@ -8,8 +8,8 @@
  * 0: Stats array <ARRAY>
  * 1: Item config path <CONFIG>
  * 2: Args for configExtreme <ARRAY>
- *  2.0: Stats limits <ARRAY of BOOLS>
+ * - 0: Stats limits <ARRAY of BOOLS>
- *  2.1: Bar limits <ARRAY of NUMBERS>
+ * - 1: Bar limits <ARRAY of NUMBERS>
  *
  * Return Value:
  * Number

addons/arsenal/functions/fnc_statBarStatement_rateOfFIre.sqf

@@ -7,8 +7,8 @@
  * 0: Not used
  * 1: Item config path <CONFIG>
  * 2: Args <ARRAY>
- *  2.0: Stat limits <ARRAY of BOOLS>
+ * - 0: Stat limits <ARRAY of BOOLS>
- *  2.1: Bar limits <ARRAY of NUMBERS>
+ * - 1: Bar limits <ARRAY of NUMBERS>
  *
  * Return Value:
  * Number

addons/common/functions/fnc_unloadUnitWeapon.sqf

@@ -14,7 +14,7 @@
  * None
  *
  * Example:
-* [ACE_player, currentWeapon ACE_player, currentMuzzle ACE_player, 23, false] call ace_common_fnc_unloadUnitWeapon
+ * [ACE_player, currentWeapon ACE_player, currentMuzzle ACE_player, 23, false] call ace_common_fnc_unloadUnitWeapon
  *
  * Public: No
  */

addons/common/functions/fnc_watchVariable.sqf

@@ -8,11 +8,11 @@
  * 1: Code to generate result (passed nothing, can return any) <CODE> (default: {})
  * 2: Array containing modifiers <ARRAY> (default: [])
  *   For Numbers:
- *     2.0: Show Delta change <BOOL> (default: true)
+ * - 0: Show Delta change <BOOL> (default: true)
- *     2.1: Slider Min Value <NUMBER> (default: 0)
+ * - 1: Slider Min Value <NUMBER> (default: 0)
- *     2.1: Slider Max Value <NUMBER> (default: 0)
+ * - 2: Slider Max Value <NUMBER> (default: 0)
  *   For Anything else:
- *     2.0: Number of structured text lines <NUMBER> (default: 1)
+ * + 0: Number of structured text lines <NUMBER> (default: 1)
  *
  * Return Value:
  * None

addons/cookoff/functions/fnc_detonateAmmunition.sqf

@@ -6,8 +6,8 @@
  * Arguments:
  * 0: vehicle <OBJECT>
  * 1: Ammo Array <ARRAY>
- *      0: Magazine Classname <STRING>
+ * - 0: Magazine Classname <STRING>
- *      1: Ammo Count <NUMBER>
+ * - 1: Ammo Count <NUMBER>
  * 2: Total Ammo Count <NUMBER>
  *
  * Return Value:

addons/cookoff/functions/fnc_getVehicleAmmo.sqf

@@ -8,8 +8,8 @@
  *
  * Return Value:
  * 0: Ammo Array <ARRAY>
- *      0: Magazine Classname <STRING>
+ * - 0: Magazine Classname <STRING>
- *      1: Ammo Count <NUMBER>
+ * - 1: Ammo Count <NUMBER>
  * 1: Total Ammo Count <NUMBER>
  *
  * Example:

addons/dragging/functions/fnc_carryObjectPFH.sqf

@@ -5,9 +5,9 @@
  *
  * Arguments:
  * 0: Arguments <ARRAY>
- *  0.0: Unit <OBJECT>
+ * - 0: Unit <OBJECT>
- *  0.1: Target <OBJECT>
+ * - 1: Target <OBJECT>
- *  0.2: Start time <NUMBER>
+ * - 2: Start time <NUMBER>
  * 1: PFEH Id <NUMBER>
  *
  * Return Value:

addons/dragging/functions/fnc_dragObjectPFH.sqf

@@ -5,9 +5,9 @@
  *
  * Arguments:
  * 0: Arguments <ARRAY>
- *  0.0: Unit <OBJECT>
+ * - 0: Unit <OBJECT>
- *  0.1: Target <OBJECT>
+ * - 1: Target <OBJECT>
- *  0.2: Start time <NUMBER>
+ * - 2: Start time <NUMBER>
  * 1: PFEH Id <NUMBER>
  *
  * Return Value:

addons/dragging/functions/fnc_startCarryPFH.sqf

@@ -5,9 +5,9 @@
  *
  * Arguments:
  * 0: Arguments <ARRAY>
- *  0.0: Unit <OBJECT>
+ * - 0: Unit <OBJECT>
- *  0.1: Target <OBJECT>
+ * - 1: Target <OBJECT>
- *  0.2: Timeout <NUMBER>
+ * - 2: Timeout <NUMBER>
  * 1: PFEH Id <NUMBER>
  *
  * Return Value:

addons/dragging/functions/fnc_startDragPFH.sqf

@@ -5,9 +5,9 @@
  *
  * Arguments:
  * 0: Arguments <ARRAY>
- *  0.0: Unit <OBJECT>
+ * - 0: Unit <OBJECT>
- *  0.1: Target <OBJECT>
+ * - 1: Target <OBJECT>
- *  0.2: Timeout <NUMBER>
+ * - 2: Timeout <NUMBER>
  * 1: PFEH Id <NUMBER>
  *
  * Return Value:

addons/explosives/functions/fnc_detonateExplosive.sqf

@@ -7,8 +7,8 @@
  * 0: Unit <OBJECT>
  * 1: Max range (-1 to ignore) <NUMBER>
  * 2: Explosive <ARRAY>
- *   2.0: Explosive <OBJECT>
+ * - 0: Explosive <OBJECT>
- *   2.1: Fuse time <NUMBER>
+ * - 1: Fuse time <NUMBER>
  * 3: Trigger Item Classname <STRING>
  *
  * Return Value:

addons/explosives/functions/fnc_detonateExplosiveAll.sqf

@@ -7,8 +7,8 @@
  * 0: Unit <OBJECT>
  * 1: Range (-1 to ignore) <NUMBER>
  * 2: Explosives to detonate <ARRAY>
- *     0: Explosive <OBJECT>
+ * - 0: Explosive <OBJECT>
- *     1: Fuse time <NUMBER>
+ * - 1: Fuse time <NUMBER>
  * 3: Trigger Item Classname <STRING>
  *
  * Return Value:

addons/fortify/functions/fnc_modifyAction.sqf

@@ -1,5 +1,5 @@
 #include "script_component.hpp"
- /*
+/*
  * Author: PabstMirror
  * Modifies the fortify action, shows current budget.
  *

addons/goggles/functions/fnc_isInRotorWash.sqf

@@ -9,8 +9,8 @@
  *
  * Return Value:
  * Array <ARRAY>:
- *     0: In rotorwash <BOOL>
+ * - 0: In rotorwash <BOOL>
- *     1: Amount of rotor wash. <NUMBER>
+ * - 1: Amount of rotor wash. <NUMBER>
  *
  * Example:
  * if ([ace_player, 10] call ace_goggles_fnc_isInRotorWash select 0) then { hint "Rotor wash"; };

addons/hearing/functions/fnc_updateVolume.sqf

@@ -5,7 +5,7 @@
  *
  * Arguments:
  * 0: Args <ARRAY>
- *   0: Just update volume (skip ringing/recovery) <BOOL> (default: false)
+ * - 0: Just update volume (skip ringing/recovery) <BOOL> (default: false)
  *
  * Return Value:
  * None

addons/laser/functions/fnc_findLaserSource.sqf

@@ -6,7 +6,7 @@
  * Arguments:
  * 0: Vehicle (shooter of laser) <OBJECT>
  * 6: Method Args <ARRAY>
- *      0: Laser Source selection on Vehicle <STRING>
+ * - 0: Laser Source selection on Vehicle <STRING>
  *
  * Return Value:
  * [position, direction] <ARRAY>

addons/repair/functions/fnc_setDamage.sqf

@@ -6,7 +6,7 @@
  * Arguments:
  * 0: Local Vehicle to Damage <OBJECT>
  * 1: Total Damage <NUMBER>
- # 2: Use destruction effects <BOOL>
+ * 2: Use destruction effects <BOOL>
  *
  * Return Value:
  * None

addons/zeus/functions/fnc_getModuleDestination.sqf

@@ -5,14 +5,13 @@
  *
  * Arguments:
  * 0: The souce object <OBJECT>
- * 1: Code to run when position is ready <CODE>
+ * 1: Code to run when position is ready (will be passed the following array) <CODE>
- * - Code is passed
+ * - 0: Successful <BOOL>
- *  0: Successful <BOOL>
+ * - 1: Object <OBJECT>
- *  1: Object <OBJECT>
+ * - 2: Position ASL <ARRAY>
- *  2: Position ASL <ARRAY>
+ * - 3: State of Shift <BOOL>
- *  3: State of Shift <BOOL>
+ * - 4: State of Ctrl <BOOL>
- *  4: State of Ctrl <BOOL>
+ * - 5: State of Alt <BOOL>
- *  5: State of Alt <BOOL>
  * 2: Text <STRING> (default: "")
  * 3: Icon image file <STRING> (default: "\a3\ui_f\data\IGUI\Cfg\Cursors\select_target_ca.paa")
  * 4: Icon color <ARRAY> (default: [1,0,0,1])

docs/tools/document_functions.py

@@ -67,6 +67,10 @@ class FunctionFile:
         self.debug = debug
         self.lint_private = lint_private
 
+        for lineNumber, line in enumerate(self.header.splitlines()):
+            if (not (line.startswith(" * ") or line in ["", " *", "/*", "*/", " */"])):
+                self.feedback(f"header formating on line {lineNumber+1}: ({line})", 1)
+
         # Preemptively cut away the comment characters (and leading/trailing whitespace)
         self.header_text = "\n".join([x[3:].strip() for x in self.header.splitlines()])
 
@@ -160,18 +164,30 @@ class FunctionFile:
             self.feedback("No blank line after arguments list", 1)
 
         arguments = []
+        expectedMainIndex = 0
+        expectedSubIndex = 0
         for argument in lines:
-            valid = re.match(r"^(\d+):\s(.+?)\<([\s\w,\|]+?)\>( )?(\s\(default: (.+)\))?$", argument)
+            valid = re.match(r"^(- ){0,1}(\d+):\s(.+?)\<([\s\w,\|]+?)\>( )?(\s\(default: (.+)\))?$", argument)
 
             if valid:
-                arg_index = valid.group(1)
+                arg_isSubIndex = valid.group(1) is not None
-                arg_name = valid.group(2)
+                arg_index = valid.group(2)
-                arg_types = valid.group(3)
+                arg_name = valid.group(3)
-                arg_default = valid.group(6)
+                arg_types = valid.group(4)
+                arg_default = valid.group(7)
                 arg_notes = []
 
-                if arg_index != str(len(arguments)):
+                if arg_isSubIndex:
-                    self.feedback("Argument index {} does not match listed order".format(arg_index), 1)
+                    expectedIndex = expectedSubIndex
+                    expectedSubIndex = expectedSubIndex + 1
+                else:
+                    expectedIndex = expectedMainIndex
+                    expectedMainIndex = expectedMainIndex + 1
+                    expectedSubIndex = 0
+
+                if int(arg_index) != expectedIndex:
+                    print(f"line|{argument}|")
+                    self.feedback(f"Argument index {arg_index} does not match listed order {expectedIndex}", 1)
 
                 if arg_default is None:
                     arg_default = ""
@@ -255,7 +271,7 @@ class FunctionFile:
             self.errors += 1
 
     def write(self, message, indent=2):
-        to_print = ["  "]*indent
+        to_print = ["  "] * indent
         to_print.append(message)
         print("".join(to_print))
 

docs/wiki/development/coding-guidelines.md

@@ -188,7 +188,9 @@ Every function should have a header of the following format appear before any co
  *
  * Arguments:
  * 0: The first argument <STRING>
- * 1: The second argument <OBJECT>
+ * 1: The second argument which contains sub values <ARRAY>
+ * - 0: Number of bannanas <NUMBER>
+ * - 1: Bannana Color <STRING>
  * 2: Multiple input types <STRING|ARRAY|CODE>
  * 3: Optional input <BOOL> (default: true)
  * 4: Optional input with multiple types <CODE|STRING> (default: {true})