Improve annotations

engine/Sim/CAiBrain.lua

@@ -229,8 +229,8 @@ function CAiBrain:GetAttackVectors()
 end
 
 --- Returns a list of factories at a location
----@param location table table with location, it's not a position but location created by PBMAddBuildLocation function
----@param radius number
+---@param location? table table with location, it's not a position but location created by PBMAddBuildLocation function
+---@param radius? number
 ---@return FactoryUnit[]
 function CAiBrain:GetAvailableFactories(location, radius)
 end
@@ -331,8 +331,8 @@ end
 --- ..........   ....xxx...
 --- ..........   ..........
 ---@param restriction boolean
----@param threatType BrainThreatType
----@param armyIndex number defaults to use all enemy armies.
+---@param threatType? BrainThreatType
+---@param armyIndex? number defaults to use all enemy armies.
 ---@return Vector
 ---@return number
 function CAiBrain:GetHighestThreatPosition(ring, restriction, threatType, armyIndex)
@@ -478,8 +478,14 @@ end
 function CAiBrain:NumCurrentlyBuilding(entityCategoryOfBuildee, entityCategoryOfBuilder)
 end
 
---- TODO.
-function CAiBrain:PickBestAttackVector()
+---TODO.
+---@param platoon Platoon
+---@param squad PlatoonSquads
+---@param alliance AllianceType
+---@param category EntityCategory
+---@param compareType any
+---@return Vector
+function CAiBrain:PickBestAttackVector(platoon, squad, alliance, category, compareType)
 end
 
 --- Returns true if platoon exists.

engine/Sim/CPlatoon.lua

@@ -188,7 +188,7 @@ end
 --- Orders platoon to assist the target unit.
 -- If squad is specified, assists the unit only with the squad.
 ---@param target Unit
----@param squad PlatoonSquadType
+---@param squad? PlatoonSquadType
 ---@return PlatoonCommand
 function CPlatoon:GuardTarget(target, squad)
 end

lua/AI/OpAI/BaseManager.lua

@@ -8,12 +8,12 @@
 
 -- types that originate from the map
 
----@class MarkerChain: string                   # Name reference to a marker chain as defined in the map
+---@alias MarkerChain Marker[]                 # Name reference to a marker chain as defined in the map
 ---@class Area: string                          # Name reference to a area as defined in the map
 ---@class UnitGroup: string                     # Name reference to a unit group as defined in the map
 
 ---@class Marker: string                        # Name reference to a marker as defined in the map
----@field Position Vector                       # A { x, y, z } array-based table
+---@field position Vector                       # A { x, y, z } array-based table
 
 -- types commonly used in repository
 
@@ -63,6 +63,21 @@
 ---@field Retry boolean                         # Flag that allows the AI to retry
 ---@field PlatoonData PlatoonData               # Parameters of the platoon AI function
 
+-- types used by the BaseManager
+
+---@class BaseEngineerCount
+---@field [1] integer Maximum number of engineers
+---@field [2] integer Engineers permanenly assisting factories, has to be <= max number
+
+---@class EngineerDifficultyCount
+---@field [1] integer Number of engineers for Easy difficulty
+---@field [2] integer Number of engineers for Medium difficulty
+---@field [3] integer Number of engineers for Hard difficulty
+
+---@class BaseEngineerDifficultyCount
+---@field [1] EngineerDifficultyCount Maximum number of engineers
+---@field [2] EngineerDifficultyCount Engineers permanenly assisting factories, has to be <= max number
+
 local AIUtils = import("/lua/ai/aiutilities.lua")
 
 local ScenarioUtils = import("/lua/sim/scenarioutilities.lua")
@@ -182,7 +197,7 @@ end
 
 --- Failsafe function that will upgrade factories, radar, etc. to next level
 ---@param unit Unit
----@param upgradeID Upgrade Blueprint
+---@param upgradeID UnitId Blueprint
 function FailSafeUpgradeBaseManagerStructure(unit, upgradeID)
 	-- Add callback when the structure starts building something
 	if not unit.AddedUpgradeCallback then
@@ -229,9 +244,9 @@ end
 
 ---@class BaseManager
 ---@field Trash TrashBag
----@field AIBrain AIBrain
+---@field AIBrain CampaignAIBrain
 ---@field Active boolean
----@field BaseName UnitGroup
+---@field BaseName string
 ---@field Position Vector
 ---@field Radius number
 ---@field CurrentEngineerCount integer
@@ -363,9 +378,9 @@ BaseManager = ClassSimple {
     --- Initialises the base manager.
     ---@see See the functions StartNonZeroBase, StartDifficultyBase, StartBase or StartEmptyBase to the initial state of the base
     ---@param self BaseManager          # An instance of the BaseManager class
-    ---@param brain AIBrain             # An instance of the Brain class that we're managing a base for
-    ---@param baseName UnitGroup        # Name reference to a unit group as defined in the map that represnts the base, usually appended with _D1, _D2 or _D3
-    ---@param markerName Marker         # Name reference to a marker as defined in the map that represents the center of the base
+    ---@param brain CampaignAIBrain     # An instance of the Brain class that we're managing a base for
+    ---@param baseName string           # Name reference to a unit group as defined in the map that represnts the base, usually appended with _D1, _D2 or _D3
+    ---@param markerName MarkerName     # Name reference to a marker as defined in the map that represents the center of the base
     ---@param radius number             # Radius of the base - any structure that is within this distance to the center of the base is considered part of the base
     ---@param levelTable any            # A table of { { UnitGroup, Priority } } that represents the priority of various sections of the base
     ---@param diffultySeparate any      # Flag that indicates we have a base that expands based on difficulty
@@ -439,7 +454,7 @@ BaseManager = ClassSimple {
     --- Initialises the base manager using the _D1, _D2 and _D3 difficulty tables.
     ---@see See the functions StartNonZeroBase, StartDifficultyBase, StartBase or StartEmptyBase to the initial state of the base
     ---@param self BaseManager          # An instance of the BaseManager class
-    ---@param brain AIBrain             # An instance of the Brain class that we're managing a base for
+    ---@param brain CampaignAIBrain     # An instance of the Brain class that we're managing a base for
     ---@param baseName UnitGroup        # Name reference to a unit group as defined in the map that represnts the base, usually appended with _D1, _D2 or _D3
     ---@param markerName Marker         # Name reference to a marker as defined in the map that represents the center of the base
     ---@param radius number             # Radius of the base - any structure that is within this distance to the center of the base is considered part of the base
@@ -599,8 +614,8 @@ BaseManager = ClassSimple {
     ---@param self BaseManager      # An instance of the BaseManager class
     ---@param groupName UnitGroup   # Name reference to a unit group as defined in the map that represents the unit group to build
     ---@param priority number       # Priority that indicates how important this build group is in comparison to others
-    ---@param spawn boolean         # Flag that indicates whether the build group is immediately spawned
-    ---@param initial boolean       # ??
+    ---@param spawn? boolean        # Flag that indicates whether the build group is immediately spawned
+    ---@param initial? boolean      # Triggers sorting of the groups by priority. It is used only internally when the base manager is first initialized with multiple groups
     ---@return nil
     AddBuildGroup = function(self, groupName, priority, spawn, initial)
         -- Make sure the group exists
@@ -631,9 +646,8 @@ BaseManager = ClassSimple {
     ---@param self BaseManager      # An instance of the BaseManager class
     ---@param groupName UnitGroup   # Name reference to a unit group as defined in the map that represents the unit group to build, appends the _D1, _D2 or _D3 to indicate difficulty
     ---@param priority number       # Priority that indicates how important this build group is in comparison to others
-    ---@param spawn boolean         # Flag that indicates whether the build group is immediately spawned
-    ---@param initial boolean       # ??
-    ---@return nil
+    ---@param spawn? boolean         # Flag that indicates whether the build group is immediately spawned
+    ---@param initial? boolean       # ??
     AddBuildGroupDifficulty = function(self, groupName, priority, spawn, initial)
         groupName = groupName .. '_D' .. ScenarioInfo.Options.Difficulty
         self:AddBuildGroup(groupName, priority, spawn, initial)
@@ -642,7 +656,6 @@ BaseManager = ClassSimple {
     --- Removes a build group from the base manager
     ---@param self BaseManager      # An instance of the BaseManager class
     ---@param groupName UnitGroup   # Name reference to a unit group as defined in the map that represents the unit group to be removed
-    ---@return nil
     ClearGroupTemplate = function(self, groupName)
         self.AIBrain.BaseTemplate[self.BaseName .. groupName] = { Template = {}, List = {}, UnitNames = {},
             BuildCounter = {} }
@@ -865,15 +878,14 @@ BaseManager = ClassSimple {
     SetEngineerCountAlt = function(self, count)
     end,
 
-    ---comment
+    ---Sets the maximum number of engineers operating in the base, this number includes commander if its spawned.
     ---@param self BaseManager      # An instance of the BaseManager class
-    ---@param count integer | table
+    ---@param count BaseEngineerDifficultyCount | BaseEngineerCount | integer If we have a table, we have various possible ways of counting engineers
+    --- {tNum1, tNum2, tNum3} - This is a difficulty defined total number of engs
+    --- {{tNum1, tNum2, tNum3,}, {aNum1, aNum2, aNum3}} - This is a difficulty defined total and permanent assisters
+    --- {tNum, aNum} - This is a single defined total with permanent assist
+    --- num - this is the number of total engineers
     SetEngineerCount = function(self, count)
-        -- If we have a table, we have various possible ways of counting engineers
-        -- {tNum1, tNum2, tNum3} - This is a difficulty defined total number of engs
-        -- {{tNum1, tNum2, tNum3,}, {aNum1, aNum2, aNum3}} - This is a difficulty defined total and permanent assisters
-        -- {tNum, aNum} - This is a single defined total with permanent assist
-        -- num - this is the number of total engineers
         if type(count) == 'table' then
             -- Table of tables means set the permanent assist count with total count
             if type(count[1]) == 'table' then
@@ -891,7 +903,7 @@ BaseManager = ClassSimple {
                 error('*Base Manager Error: Unknown number of entries passed to SetEngineerCount')
             end
         else
-            self:SetTotalEngineerCount(count)
+            self:SetTotalEngineerCount(count--[[@as integer]])
         end
     end,
 
@@ -1032,7 +1044,7 @@ BaseManager = ClassSimple {
     ---@param self BaseManager
     ---@param upgradeTable table
     ---@param unitName string
-    ---@param startActive boolean
+    ---@param startActive? boolean
     ---@return boolean
     SetUnitUpgrades = function(self, upgradeTable, unitName, startActive)
         if not unitName then
@@ -1131,14 +1143,14 @@ BaseManager = ClassSimple {
 
     ---@param self BaseManager
     ---@param upgradeTable table
-    ---@param startActive boolean
+    ---@param startActive? boolean
     SetACUUpgrades = function(self, upgradeTable, startActive)
         self:SetUnitUpgrades(upgradeTable, 'DefaultACU', startActive)
     end,
 
     ---@param self BaseManager
     ---@param upgradeTable table
-    ---@param startActive boolean
+    ---@param startActive? boolean
     SetSACUUpgrades = function(self, upgradeTable, startActive)
         self:SetUnitUpgrades(upgradeTable, 'DefaultSACU', startActive)
     end,
@@ -1198,8 +1210,8 @@ BaseManager = ClassSimple {
     --- Spawns a group, tracks number of times it has been built, gives nuke and anti-nukes ammo
     ---@param self BaseManager
     ---@param groupName string
-    ---@param uncapturable boolean
-    ---@param balance number
+    ---@param uncapturable? boolean
+    ---@param balance? number
     SpawnGroup = function(self, groupName, uncapturable, balance)
         local unitGroup = ScenarioUtils.CreateArmyGroup(self.AIBrain.Name, groupName, nil, balance)
 
@@ -1235,8 +1247,8 @@ BaseManager = ClassSimple {
 
     --- Sets Engineer Count, spawns in all groups that have priority greater than zero
     ---@param self BaseManager
-    ---@param engineerNumber number|table
-    ---@param uncapturable boolean
+    ---@param engineerNumber? integer|table Defaults to 0
+    ---@param uncapturable? boolean
     StartNonZeroBase = function(self, engineerNumber, uncapturable)
         if not engineerNumber and not ScenarioInfo.VarTable[self.BaseName .. '_EngineerNumber'] then
             self:SetEngineerCount(0)
@@ -1256,9 +1268,9 @@ BaseManager = ClassSimple {
     end,
 
     ---@param self BaseManager
-    ---@param groupNames string
-    ---@param engineerNumber number
-    ---@param uncapturable boolean
+    ---@param groupNames string[]
+    ---@param engineerNumber? integer Defaults to 0
+    ---@param uncapturable? boolean
     StartDifficultyBase = function(self, groupNames, engineerNumber, uncapturable)
         local newNames = {}
         for k, v in groupNames do
@@ -1270,8 +1282,8 @@ BaseManager = ClassSimple {
     -- Sets engineer count, spawns in all groups passed in in groupNames table
     ---@param self BaseManager
     ---@param groupNames table
-    ---@param engineerNumber number
-    ---@param uncapturable boolean
+    ---@param engineerNumber? integer Defaults to 0
+    ---@param uncapturable? boolean
     StartBase = function(self, groupNames, engineerNumber, uncapturable)
         if not engineerNumber and not ScenarioInfo.VarTable[self.BaseName .. '_EngineerNumber'] then
             self:SetEngineerCount(0)
@@ -1291,7 +1303,7 @@ BaseManager = ClassSimple {
 
     -- Sets engineer count and spawns in no groups
     ---@param self BaseManager
-    ---@param engineerNumber number
+    ---@param engineerNumber? integer Defaults to 1
     StartEmptyBase = function(self, engineerNumber)
         if not engineerNumber and not ScenarioInfo.VarTable[self.BaseName .. '_EngineerNumber'] then
             self:SetEngineerCount(1)
@@ -1477,7 +1489,7 @@ BaseManager = ClassSimple {
     -- Enable/Disable functionality of base parts through functions
     ---@param self BaseManager
     ---@param actType string
-    ---@param val number
+    ---@param val boolean
     SetActive = function(self, actType, val)
         if self.ActivationFunctions[actType .. 'Active'] then
             self.ActivationFunctions[actType .. 'Active'](self, val)
@@ -2121,12 +2133,14 @@ BaseManager = ClassSimple {
 }
 
 --- Prepares a base manager, note that you still need to call one of the Start functions
+--- If no params are provided, the base manager is only created, but not initialized
 ---@param brain AIBrain
 ---@param baseName UnitGroup
 ---@param markerName Marker
 ---@param radius number
 ---@param levelTable table
 ---@return BaseManager
+---@overload fun(): BaseManager
 function CreateBaseManager(brain, baseName, markerName, radius, levelTable)
 
     ---@type BaseManager

lua/AI/aibuildstructures.lua

@@ -8,7 +8,7 @@ local BaseTmplFile = lazyimport("/lua/basetemplates.lua")
 local StructureTemplates = import("/lua/buildingtemplates.lua")
 local Utils = import("/lua/utilities.lua")
 local AIUtils = import("/lua/ai/aiutilities.lua")
-local ScenarioUtils = import("/lua/sim/scenarioutilities.lua")
+local ScenarioUtils = import("/lua/sim/ScenarioUtilities.lua")
 local aiEconomy
 local allowedEnergyStorageRatio = 0.7
 local allowedMassStorageRatio = 0.6

lua/AI/aiutilities.lua

@@ -444,10 +444,10 @@ end
 ---@param markerType string
 ---@param pos Vector
 ---@param radius number
----@param threatMin number
----@param threatMax number
----@param threatRings number
----@param threatType string
+---@param threatMin? number
+---@param threatMax? number
+---@param threatRings? number
+---@param threatType? string
 ---@return table
 function AIGetMarkerPositionsAroundLocation(aiBrain, markerType, pos, radius, threatMin, threatMax, threatRings, threatType)
     local markers = AIGetMarkersAroundLocation(aiBrain, markerType, pos, radius, threatMin, threatMax, threatRings, threatType)
@@ -463,10 +463,10 @@ end
 ---@param markerType string
 ---@param pos Vector
 ---@param radius number
----@param threatMin number
----@param threatMax number
----@param threatRings number
----@param threatType string
+---@param threatMin? number
+---@param threatMax? number
+---@param threatRings? number
+---@param threatType? string
 ---@return table
 function AIGetMarkersAroundLocation(aiBrain, markerType, pos, radius, threatMin, threatMax, threatRings, threatType)
     local markers = import("/lua/sim/markerutilities.lua").GetMarkersByType(markerType)
@@ -1309,9 +1309,9 @@ end
 ---@param category EntityCategory
 ---@param location Vector
 ---@param radius number
----@param min number
----@param max number
----@param rings number
+---@param min? number
+---@param max? number
+---@param rings? number
 ---@param tType? string
 ---@return table
 function GetOwnUnitsAroundPoint(aiBrain, category, location, radius, min, max, rings, tType)