Various annotations

.vscode/settings.json

@@ -23,7 +23,22 @@
   "Lua.runtime.pathStrict": false,
   "Lua.runtime.exportEnvDefault": true,
   "Lua.completion.autoRequire": false,
-  "Lua.diagnostics.globals": ["ScenarioInfo", "__moduleinfo"],
+  "Lua.diagnostics.globals": [
+    "ScenarioInfo",
+    "__moduleinfo",
+    "sortedpairs",
+    "sort_by",
+    "sort_down_by",
+    "safecall",
+    "printField",
+    "__diskwatch",
+    "repr",
+    "repru",
+    "reprs",
+    "reprsl",
+    "__language",
+    "__installedlanguages"
+  ],
   "Lua.format.defaultConfig": {
     "max_line_length": "unset",
   },

changelog/snippets/other.7179.md

@@ -0,0 +1 @@
+- Annotate some engine behavior and miscellaneous lua functions (#7179).

engine/Core/Categories.lua

@@ -149,6 +149,7 @@ categories = {
     OVERLAYOMNI = categoryValue,
     OVERLAYRADAR = categoryValue,
     OVERLAYSONAR = categoryValue,
+    -- Allows unit to reclaim and repair on patrol/aggressive move tasks.
     PATROLHELPER = categoryValue,
     PERSONALSHIELD = categoryValue,
     POD = categoryValue,

engine/Sim.lua

@@ -43,7 +43,9 @@ ArmyBrains = {}
 function AddBuildRestriction(army, category)
 end
 
---- it is unknown what this function does or where it gets its value from
+--- it is unknown what this function fully does or where it gets its value from
+--- 
+--- Reduces damage dealt by this army after armor by dividing by `1 + handicap`.
 ---@param army Army
 ---@deprecated
 function ArmyGetHandicap(army)

engine/Sim/Unit.lua

@@ -734,4 +734,8 @@ end
 function Unit:TransportHasSpaceFor(target)
 end
 
-return Unit
+--- Called by the engine when the unit takes >= 2 times as much damage due to armor multi or handicap divisor.
+---@type fun(self: Unit, type: DamageType)
+Unit.OnExtraDamageDealt = nil
+
+return Unit

lua/maui/group.lua

@@ -1,6 +1,7 @@
 local Control = import("/lua/maui/control.lua").Control
 
 ---@class Group : moho.group_methods, Control, InternalObject
+---@overload fun(parent: Control, debugname: string?): Group
 Group = ClassUI(moho.group_methods, Control) {
     ---@param self Group
     ---@param parent Control

lua/sim/Unit.lua

@@ -5336,8 +5336,9 @@ Unit = ClassUnit(moho.unit_methods, IntelComponent, VeterancyComponent, DebugUni
     ---@param location number
     OnSpecialAction = function(self, location) end,
 
+    --- Called by the engine when the unit is damaged by an army.
     ---@param self Unit
-    ---@param index integer
+    ---@param index Army
     OnDamageBy = function(self, index) end,
 
     --- Deprecated functionality

lua/system/utils.lua

@@ -352,7 +352,11 @@ end
 ---   for k,v in sortedpairs(t) do
 ---       print(k,v)
 ---   end
---- @param comp is an optional comparison function, defaulting to less-than.
+--- comp is an optional comparison function, defaulting to less-than.
+---@generic K, V
+---@param t table<K, V>
+---@param comp? fun(a: K, b: K):boolean
+---@return fun(): K, V
 function sortedpairs(t, comp)
     local keys = table.keys(t, comp)
     local i=1
@@ -393,7 +397,7 @@ function table.reverse(t)
 end
 
 --- Combines a series of tables into one table. Returns a new table. The parameters are merged into the new table in order
----@see `table.assimilate`
+---@see table.assimilate
 ---@param ... table[]
 ---@return table
 function table.combine(...)
@@ -554,9 +558,10 @@ function table.print(tbl, tblPrefix, printer)
     printer(tblPrefix.." }")
 end
 
---- Return filtered table containing every mapping from table for which fn function returns true when passed the value.
---- @param t  - is a table to filter
---- @param fn - is decision function to use to filter the table, defaults checking if a value is true or exists in table
+--- Return shallow-copied, filtered table containing every mapping from table for which function `fn` returns true when passed the value.
+---@generic K, V
+---@param t table<K, V> # table to filter
+---@param fn? fun(value: V): boolean # Value filter function. Defaults to checking if a value is truthy
 function table.filter(t, fn)
     local r = {}
     if not fn then fn = function(v) return v end end
@@ -568,8 +573,10 @@ function table.filter(t, fn)
     return r
 end
 
---- Returns total count of values that match fn function or if values exist in table
---- @param fn is optional filtering function that is applied to each value of the table
+--- Returns total count of values that match function `fn`
+---@generic K, V
+---@param t table<K, V>
+---@param fn? fun(value: V): boolean # Defaults to checking if value is truthy
 function table.count(t, fn)
     if not t then return 0 end -- prevents looping over nil table
     if not fn then fn = function(v) return v end end
@@ -660,6 +667,7 @@ end
 function StringComma(value)
     local str = value or 0
     while true do
+      local k
       str, k = string.gsub(str, "^(-?%d+)(%d%d%d)", '%1,%2')
       if k == 0 then
         break