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

* tools - handle header sub indexs for arguements * convert remaining * Update coding-guidelines.md
2024-08-30 18:23:18 +00:00 · 2023-08-08 22:51:20 -05:00 · 2023-08-08 22:51:20 -05:00 · eb53e7a2fe
commit eb53e7a2fe
parent f941e0217b
32 changed files with 99 additions and 83 deletions
--- a/addons/arsenal/functions/fnc_addSort.sqf
+++ b/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.1: Right Tab Indexes <ARRAY of NUMBERS>
+ * - 0: Left 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>
--- a/addons/arsenal/functions/fnc_addStat.sqf
+++ b/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.1: Right tab indexes <ARRAY of NUMBERS>
+ * - 0: Left 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)
- *   4.1: Show text <BOOL> (default: false)
+ * - 0: Show bar <BOOL> (default: false)
+ * - 1: Show text <BOOL> (default: false)
 * 5: Array of statements <ARRAY of CODE>
- *   5.0: Bar code <CODE> (default: {})
- *   5.1: Text code <CODE> (default: {})
- *   5.2: Condition code <CODE> (default: {true})
+ * - 0: Bar code <CODE> (default: {})
+ * - 1: Text code <CODE> (default: {})
+ * - 2: Condition code <CODE> (default: {true})
 * 6: Priority <NUMBER> (default: 0)
 *
 * Return Value:
--- a/addons/arsenal/functions/fnc_handleMouse.sqf
+++ b/addons/arsenal/functions/fnc_handleMouse.sqf
@ -8,9 +8,9 @@
 * Arguments:
 * 0: Not used
 * 1: Arguments <ARRAY>
-  * 1.0: Mouse area control <CONTROL>
-  * 1.1: Mouse X position <NUMBER>
-  * 1.2: Mouse Y position <NUMBER>
+ * - 0: Mouse area control <CONTROL>
+ * - 1: Mouse X position <NUMBER>
+ * - 2: Mouse Y position <NUMBER>
 *
 * Return Value:
 * None
--- a/addons/arsenal/functions/fnc_handleScrollWheel.sqf
+++ b/addons/arsenal/functions/fnc_handleScrollWheel.sqf
@ -6,8 +6,8 @@
 * Arguments:
 * 0: Not used
 * 1: onMouseZChanged EH return <ARRAY>
- *  1.0: Not used
- *  1.1: Mousewheel Z position <NUMBER>
+ * - 0: Not used
+ * - 1: Mousewheel Z position <NUMBER>
 *
 * Return Value:
 * None
--- a/addons/arsenal/functions/fnc_onArsenalClose.sqf
+++ b/addons/arsenal/functions/fnc_onArsenalClose.sqf
@ -6,8 +6,8 @@
 * Arguments:
 * 0: Not used
 * 1: Args <ARRAY>
- *   1.0: Not used
- *   1.1: Exit code <NUMBER>
+ * - 0: Not used
+ * - 1: Exit code <NUMBER>
 *
 * Return Value:
 * None
--- a/addons/arsenal/functions/fnc_onArsenalOpen.sqf
+++ b/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
--- a/addons/arsenal/functions/fnc_onLoadoutsOpen.sqf
+++ b/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
--- a/addons/arsenal/functions/fnc_onMouseButtonDown.sqf
+++ b/addons/arsenal/functions/fnc_onMouseButtonDown.sqf
@ -6,10 +6,10 @@
 * Arguments:
 * 0: Not used
 * 1: Args <ARRAY>
- *   1.0: Not used
- *   1.1: Mouse button <NUMBER>
- *   1.2: Mouse X position <NUMBER>
- *   1.3: Mouse Y position <NUMBER>
+ * - 0: Not used
+ * - 1: Mouse button <NUMBER>
+ * - 2: Mouse X position <NUMBER>
+ * - 3: Mouse Y position <NUMBER>
 *
 * Return Value:
 * None
--- a/addons/arsenal/functions/fnc_onMouseButtonUp.sqf
+++ b/addons/arsenal/functions/fnc_onMouseButtonUp.sqf
@ -6,8 +6,8 @@
 * Arguments:
 * 0: Not used
 * 1: Args <ARRAY>
- *   1.0: Not used
- *   1.1: Mouse button <NUMBER>
+ * - 0: Not used
+ * - 1: Mouse button <NUMBER>
 *
 * Return Value:
 * None
--- a/addons/arsenal/functions/fnc_removeSort.sqf
+++ b/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
 */
--- a/addons/arsenal/functions/fnc_statBarStatement_accuracy.sqf
+++ b/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>
- *  2.1: Bar limits <ARRAY of NUMBERS>
+ * - 0: Stat limits <ARRAY of BOOLS>
+ * - 1: Bar limits <ARRAY of NUMBERS>
 *
 * Return Value:
 * <NUMBER>
--- a/addons/arsenal/functions/fnc_statBarStatement_default.sqf
+++ b/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>
- *  2.1: Bar limits <ARRAY of NUMBERS>
- *  2.2: Evaluate as a logarithmic number <BOOL>
+ * - 0: Stat limits <ARRAY of BOOLS>
+ * - 1: Bar limits <ARRAY of NUMBERS>
+ * - 2: Evaluate as a logarithmic number <BOOL>
 *
 * Return Value:
 * Bar statement <NUMBER>
--- a/addons/arsenal/functions/fnc_statBarStatement_impact.sqf
+++ b/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>
- *  2.1: Bar limits <ARRAY of NUMBERS>
+ * - 0: Stats limits <ARRAY of BOOLS>
+ * - 1: Bar limits <ARRAY of NUMBERS>
 *
 * Return Value:
 * Number
--- a/addons/arsenal/functions/fnc_statBarStatement_rateOfFIre.sqf
+++ b/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>
- *  2.1: Bar limits <ARRAY of NUMBERS>
+ * - 0: Stat limits <ARRAY of BOOLS>
+ * - 1: Bar limits <ARRAY of NUMBERS>
 *
 * Return Value:
 * Number
--- a/addons/common/functions/fnc_unloadUnitWeapon.sqf
+++ b/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
 */
--- a/addons/common/functions/fnc_watchVariable.sqf
+++ b/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)
- *     2.1: Slider Min Value <NUMBER> (default: 0)
- *     2.1: Slider Max Value <NUMBER> (default: 0)
+ * - 0: Show Delta change <BOOL> (default: true)
+ * - 1: Slider Min 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
--- a/addons/cookoff/functions/fnc_detonateAmmunition.sqf
+++ b/addons/cookoff/functions/fnc_detonateAmmunition.sqf
@ -6,8 +6,8 @@
 * Arguments:
 * 0: vehicle <OBJECT>
 * 1: Ammo Array <ARRAY>
- *      0: Magazine Classname <STRING>
- *      1: Ammo Count <NUMBER>
+ * - 0: Magazine Classname <STRING>
+ * - 1: Ammo Count <NUMBER>
 * 2: Total Ammo Count <NUMBER>
 *
 * Return Value:
--- a/addons/cookoff/functions/fnc_getVehicleAmmo.sqf
+++ b/addons/cookoff/functions/fnc_getVehicleAmmo.sqf
@ -8,8 +8,8 @@
 *
 * Return Value:
 * 0: Ammo Array <ARRAY>
- *      0: Magazine Classname <STRING>
- *      1: Ammo Count <NUMBER>
+ * - 0: Magazine Classname <STRING>
+ * - 1: Ammo Count <NUMBER>
 * 1: Total Ammo Count <NUMBER>
 *
 * Example:
--- a/addons/dragging/functions/fnc_carryObjectPFH.sqf
+++ b/addons/dragging/functions/fnc_carryObjectPFH.sqf
@ -5,9 +5,9 @@
 *
 * Arguments:
 * 0: Arguments <ARRAY>
- *  0.0: Unit <OBJECT>
- *  0.1: Target <OBJECT>
- *  0.2: Start time <NUMBER>
+ * - 0: Unit <OBJECT>
+ * - 1: Target <OBJECT>
+ * - 2: Start time <NUMBER>
 * 1: PFEH Id <NUMBER>
 *
 * Return Value:
--- a/addons/dragging/functions/fnc_dragObjectPFH.sqf
+++ b/addons/dragging/functions/fnc_dragObjectPFH.sqf
@ -5,9 +5,9 @@
 *
 * Arguments:
 * 0: Arguments <ARRAY>
- *  0.0: Unit <OBJECT>
- *  0.1: Target <OBJECT>
- *  0.2: Start time <NUMBER>
+ * - 0: Unit <OBJECT>
+ * - 1: Target <OBJECT>
+ * - 2: Start time <NUMBER>
 * 1: PFEH Id <NUMBER>
 *
 * Return Value:
--- a/addons/dragging/functions/fnc_startCarryPFH.sqf
+++ b/addons/dragging/functions/fnc_startCarryPFH.sqf
@ -5,9 +5,9 @@
 *
 * Arguments:
 * 0: Arguments <ARRAY>
- *  0.0: Unit <OBJECT>
- *  0.1: Target <OBJECT>
- *  0.2: Timeout <NUMBER>
+ * - 0: Unit <OBJECT>
+ * - 1: Target <OBJECT>
+ * - 2: Timeout <NUMBER>
 * 1: PFEH Id <NUMBER>
 *
 * Return Value:
--- a/addons/dragging/functions/fnc_startDragPFH.sqf
+++ b/addons/dragging/functions/fnc_startDragPFH.sqf
@ -5,9 +5,9 @@
 *
 * Arguments:
 * 0: Arguments <ARRAY>
- *  0.0: Unit <OBJECT>
- *  0.1: Target <OBJECT>
- *  0.2: Timeout <NUMBER>
+ * - 0: Unit <OBJECT>
+ * - 1: Target <OBJECT>
+ * - 2: Timeout <NUMBER>
 * 1: PFEH Id <NUMBER>
 *
 * Return Value:
--- a/addons/explosives/functions/fnc_detonateExplosive.sqf
+++ b/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>
- *   2.1: Fuse time <NUMBER>
+ * - 0: Explosive <OBJECT>
+ * - 1: Fuse time <NUMBER>
 * 3: Trigger Item Classname <STRING>
 *
 * Return Value:
--- a/addons/explosives/functions/fnc_detonateExplosiveAll.sqf
+++ b/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>
- *     1: Fuse time <NUMBER>
+ * - 0: Explosive <OBJECT>
+ * - 1: Fuse time <NUMBER>
 * 3: Trigger Item Classname <STRING>
 *
 * Return Value:
--- a/addons/fortify/functions/fnc_modifyAction.sqf
+++ b/addons/fortify/functions/fnc_modifyAction.sqf
@ -1,5 +1,5 @@
 #include "script_component.hpp"
- /*
+/*
 * Author: PabstMirror
 * Modifies the fortify action, shows current budget.
 *
--- a/addons/goggles/functions/fnc_isInRotorWash.sqf
+++ b/addons/goggles/functions/fnc_isInRotorWash.sqf
@ -9,8 +9,8 @@
 *
 * Return Value:
 * Array <ARRAY>:
- *     0: In rotorwash <BOOL>
- *     1: Amount of rotor wash. <NUMBER>
+ * - 0: In rotorwash <BOOL>
+ * - 1: Amount of rotor wash. <NUMBER>
 *
 * Example:
 * if ([ace_player, 10] call ace_goggles_fnc_isInRotorWash select 0) then { hint "Rotor wash"; };
--- a/addons/hearing/functions/fnc_updateVolume.sqf
+++ b/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
--- a/addons/laser/functions/fnc_findLaserSource.sqf
+++ b/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>
--- a/addons/repair/functions/fnc_setDamage.sqf
+++ b/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
--- a/addons/zeus/functions/fnc_getModuleDestination.sqf
+++ b/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>
- * - Code is passed
- *  0: Successful <BOOL>
- *  1: Object <OBJECT>
- *  2: Position ASL <ARRAY>
- *  3: State of Shift <BOOL>
- *  4: State of Ctrl <BOOL>
- *  5: State of Alt <BOOL>
+ * 1: Code to run when position is ready (will be passed the following array) <CODE>
+ * - 0: Successful <BOOL>
+ * - 1: Object <OBJECT>
+ * - 2: Position ASL <ARRAY>
+ * - 3: State of Shift <BOOL>
+ * - 4: State of Ctrl <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])
--- a/docs/tools/document_functions.py
+++ b/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_name = valid.group(2)
-                arg_types = valid.group(3)
-                arg_default = valid.group(6)
+                arg_isSubIndex = valid.group(1) is not None
+                arg_index = valid.group(2)
+                arg_name = valid.group(3)
+                arg_types = valid.group(4)
+                arg_default = valid.group(7)
                arg_notes = []

-                if arg_index != str(len(arguments)):
-                    self.feedback("Argument index {} does not match listed order".format(arg_index), 1)
+                if arg_isSubIndex:
+                    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))

--- a/docs/wiki/development/coding-guidelines.md
+++ b/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})