Merge pull request DFHack#4577 from vallode/widgets-types

Add typing to widgets and gui

library/lua/class.lua

@@ -3,22 +3,40 @@
 local _ENV = mkmodule('class')
 
 -- Metatable template for a class
+---@class class.class_obj
+---@overload fun(init_table: table): self
 class_obj = class_obj or {}
 
 -- Methods shared by all classes
+---@class class.common_methods
 common_methods = common_methods or {}
 
 -- Forbidden names for class fields and methods.
+---@class class.reserved_names
 reserved_names = { super = true, ATTRS = true }
 
 -- Attribute table metatable
+---@class class.attrs_meta: table
+---@overload fun(attributes: table)
 attrs_meta = attrs_meta or {}
 
+---@class dfhack.class: class.common_methods, class.class_obj
+---@field super any
+---@field ATTRS class.attrs_meta|fun(attributes: class.attrs_meta)
+
 -- Create or updates a class; a class has metamethods and thus own metatable.
----@generic T: table
+--
+-- When defining a new class type with annotations, follow this pattern:
+--
+--    ---@class moduleName.ClassName: dfhack.class, moduleName.ParentClass?
+--    ---@field super moduleName.ParentClass
+--    ---@field ATTRS moduleName.ClassNameAttrs|fun(attributes: moduleName.ClassNameAttrs)
+--    ---@overload fun(init_table: moduleName.ClassNameInitTable): self
+--    ClassName = defclass(ClassName, ParentClass)
+---@generic T: dfhack.class
 ---@param class? T
 ---@param parent? table
----@return table|T
+---@return T
 function defclass(class,parent)
     class = class or {}
 
@@ -43,10 +61,10 @@ function defclass(class,parent)
 end
 
 -- An instance uses the class as metatable
----@generic T: table
----@param class table
----@param table? T
----@return table|T
+---@generic T: dfhack.class
+---@param class T
+---@param table? table
+---@return T
 function mkinstance(class,table)
     table = table or {}
     setmetatable(table, class)
@@ -141,28 +159,42 @@ end
 
 -- Common methods for all instances:
 
+---@param method string
+---@param ... unknown
+---@return unknown
 function common_methods:callback(method, ...)
     return dfhack.curry(self[method], self, ...)
 end
 
+---@param field string
+---@return function
 function common_methods:cb_getfield(field)
     return function() return self[field] end
 end
 
+---@param field string
+---@return function
 function common_methods:cb_setfield(field)
     return function(val) self[field] = val end
 end
 
+---@param data table
 function common_methods:assign(data)
     for k,v in pairs(data) do
         self[k] = v
     end
 end
 
+---@param method function
+---@param ... unknown
+---@return unknown
 function common_methods:invoke_before(method, ...)
     return invoke_before_rec(self, getmetatable(self), method, ...)
 end
 
+---@param method function
+---@param ... unknown
+---@return unknown
 function common_methods:invoke_after(method, ...)
     return invoke_after_rec(self, getmetatable(self), method, ...)
 end

library/lua/dfhack.lua

@@ -15,6 +15,17 @@ local dfhack = dfhack
 local base_env = dfhack.BASE_G
 local _ENV = base_env
 
+-- Types
+
+---@alias dfhack.truthy
+---| true
+---| integer
+---| string
+---| table
+---| function
+---| userdata
+---| fun(...): true|string|integer|table|function|userdata
+
 CR_LINK_FAILURE = -3
 CR_NEEDS_CONSOLE = -2
 CR_NOT_IMPLEMENTED = -1
@@ -46,6 +57,27 @@ COLOR_WHITE = 15
 COLOR_GRAY = COLOR_GREY
 COLOR_DARKGRAY = COLOR_DARKGREY
 
+---@alias dfhack.color
+---| `COLOR_RESET`
+---| `COLOR_BLACK`
+---| `COLOR_BLUE`
+---| `COLOR_GREEN`
+---| `COLOR_CYAN`
+---| `COLOR_RED`
+---| `COLOR_MAGENTA`
+---| `COLOR_BROWN`
+---| `COLOR_GREY`
+---| `COLOR_DARKGREY`
+---| `COLOR_LIGHTBLUE`
+---| `COLOR_LIGHTGREEN`
+---| `COLOR_LIGHTCYAN`
+---| `COLOR_LIGHTRED`
+---| `COLOR_LIGHTMAGENTA`
+---| `COLOR_YELLOW`
+---| `COLOR_WHITE`
+---| `COLOR_GRAY`
+---| `COLOR_DARKGRAY`
+
 -- Events
 
 if dfhack.is_core_context then
@@ -202,18 +234,21 @@ end
 ---@type any
 DEFAULT_NIL = DEFAULT_NIL or {} -- Unique token
 
----@generic T: table
+-- Create or updates a class; a class has metamethods and thus own metatable.
+---@nodiscard
+---@generic T: dfhack.class
 ---@param class? T
 ---@param parent? table
----@return table|T
+---@return T
 function defclass(class,parent)
     return require('class').defclass(class,parent)
 end
 
----@generic T: table
----@param class table
----@param table? T
----@return table|T
+-- An instance uses the class as metatable
+---@generic T: dfhack.class
+---@param class T
+---@param table? table
+---@return T
 function mkinstance(class,table)
     return require('class').mkinstance(class,table)
 end