boolean -> nil return values + annotation fixes

lua/AI/aiutilities.lua

@@ -620,12 +620,12 @@ end
 ---@param tRings number
 ---@param tType string
 ---@param eng? Unit
----@return boolean
----@return string
+---@return Vector?
+---@return string?
 function AIFindStartLocationNeedsEngineer(aiBrain, locationType, radius, tMin, tMax, tRings, tType, eng)
     local pos = aiBrain:PBMGetLocationCoords(locationType)
     if not pos then
-        return false
+        return
     end
 
     local validPos = AIGetMarkersAroundLocation(aiBrain, 'Large Expansion Area', pos, radius, tMin, tMax, tRings, tType)
@@ -658,12 +658,12 @@ end
 ---@param tRings number
 ---@param tType string
 ---@param eng? Unit
----@return boolean
----@return string
+---@return Vector?
+---@return string?
 function AIFindExpansionAreaNeedsEngineer(aiBrain, locationType, radius, tMin, tMax, tRings, tType, eng)
     local pos = aiBrain:PBMGetLocationCoords(locationType)
     if not pos then
-        return false
+        return
     end
     local positions = AIGetMarkersAroundLocation(aiBrain, 'Expansion Area', pos, radius, tMin, tMax, tRings, tType)
 
@@ -685,12 +685,12 @@ end
 ---@param tRings number
 ---@param tType string
 ---@param eng? Unit
----@return boolean
----@return string
+---@return Vector?
+---@return string?
 function AIFindNavalAreaNeedsEngineer(aiBrain, locationType, radius, tMin, tMax, tRings, tType, eng)
     local pos = aiBrain:PBMGetLocationCoords(locationType)
     if not pos then
-        return false
+        return
     end
     local positions = AIGetMarkersAroundLocation(aiBrain, 'Naval Area', pos, radius, tMin, tMax, tRings, tType)
 
@@ -731,12 +731,12 @@ end
 ---@param tMax number
 ---@param tRings number
 ---@param tType string
----@return boolean
----@return any
+---@return Vector?
+---@return string?
 function AIFindNavalDefensivePointNeedsStructure(aiBrain, locationType, radius, category, markerRadius, unitMax, tMin, tMax, tRings, tType)
     local pos = aiBrain:PBMGetLocationCoords(locationType)
     if not pos then
-        return false
+        return
     end
     local positions = AIGetMarkersAroundLocation(aiBrain, 'Naval Defensive Point', pos, radius, tMin, tMax, tRings, tType)
 
@@ -765,12 +765,12 @@ end
 ---@param tMax number
 ---@param tRings number
 ---@param tType string
----@return boolean
----@return any
+---@return Vector?
+---@return string?
 function AIFindDefensivePointNeedsStructure(aiBrain, locationType, radius, category, markerRadius, unitMax, tMin, tMax, tRings, tType)
     local pos = aiBrain:PBMGetLocationCoords(locationType)
     if not pos then
-        return false
+        return
     end
     local positions = AIGetMarkersAroundLocation(aiBrain, 'Defensive Point', pos, radius, tMin, tMax, tRings, tType)
 
@@ -1458,11 +1458,11 @@ end
 ---@param maxRange number
 ---@param atkPri table
 ---@param enemyBrain AIBrain|number
----@return boolean
+---@return Unit? target
 function AIFindBrainTargetInRange(aiBrain, platoon, squad, maxRange, atkPri, enemyBrain)
     local position = platoon:GetPlatoonPosition()
     if not aiBrain or not position or not maxRange or not platoon or not enemyBrain then
-        return false
+        return
     end
 
     local enemyIndex = enemyBrain:GetArmyIndex()
@@ -1473,7 +1473,7 @@ function AIFindBrainTargetInRange(aiBrain, platoon, squad, maxRange, atkPri, ene
             category = ParseEntityCategory(category)
         end
         local retUnit = false
-        local distance = false
+        local distance
         for num, unit in targetUnits do
             if not unit.Dead and EntityCategoryContains(category, unit) and unit:GetAIBrain():GetArmyIndex() == enemyIndex and platoon:CanAttackTarget(squad, unit) then
                 local unitPos = unit:GetPosition()
@@ -1488,7 +1488,7 @@ function AIFindBrainTargetInRange(aiBrain, platoon, squad, maxRange, atkPri, ene
         end
     end
 
-    return false
+    return
 end
 
 ---@param aiBrain AIBrain
@@ -2343,10 +2343,10 @@ end
 ---@param squad string
 ---@param atkPri table
 ---@param position Vector
----@return boolean
+---@return Unit? target
 function AIFindAirAttackTargetInRangeSorian(aiBrain, platoon, squad, atkPri, position)
     if not aiBrain or not position then
-        return false
+        return
     end
 
     local targetUnits = aiBrain:GetUnitsAroundPoint(categories.ALLUNITS, position, 100, 'Enemy')
@@ -2385,7 +2385,7 @@ function AIFindAirAttackTargetInRangeSorian(aiBrain, platoon, squad, atkPri, pos
         end
     end
 
-    return false
+    return
 end
 
 ---@param aiBrain AIBrain
@@ -2412,11 +2412,11 @@ end
 ---@param maxRange number
 ---@param atkPri table
 ---@param avoidbases any
----@return boolean
+---@return Unit? target
 function AIFindBrainTargetInRangeSorian(aiBrain, platoon, squad, maxRange, atkPri, avoidbases)
     local position = platoon:GetPlatoonPosition()
     if not aiBrain or not position or not maxRange then
-        return false
+        return
     end
 
     local targetUnits = aiBrain:GetUnitsAroundPoint(categories.ALLUNITS, position, maxRange, 'Enemy')
@@ -2465,7 +2465,7 @@ function AIFindBrainTargetInRangeSorian(aiBrain, platoon, squad, maxRange, atkPr
         end
     end
 
-    return false
+    return
 end
 
 ---@param aiBrain AIBrain
@@ -3118,12 +3118,12 @@ end
 ---@param tRings number
 ---@param tType string
 ---@param eng? Unit
----@return boolean
----@return unknown
+---@return Vector?
+---@return string?
 function AIFindFurthestStartLocationNeedsEngineer(aiBrain, locationType, radius, tMin, tMax, tRings, tType, eng)
     local pos = aiBrain:PBMGetLocationCoords(locationType)
     if not pos then
-        return false
+        return
     end
 
     local validPos = AIGetMarkersAroundLocation(aiBrain, 'Large Expansion Area', pos, radius, tMin, tMax, tRings, tType)
@@ -3535,6 +3535,7 @@ function GetBuildLocation(aiBrain, buildingTemplate, baseTemplate, buildUnit, en
     return false
 end
 
+---@return Marker
 function GetResourceMarkerWithinRadius(aiBrain, pos, markerType, radius, canBuild, maxThreat, threatType)
     local markers = import("/lua/sim/markerutilities.lua").GetMarkersByType(markerType)
     local markerTable = {}