Fix pointer as first argument

Author: vallode

dist/library/modules/buildings.lua

@@ -14,14 +14,13 @@ function dfhack.buildings.findAtTile(pos) end
 ---@return boolean
 function dfhack.buildings.findCivzonesAt(pvec, pos) end
 
----@param size df.coord2d
 ---@param center df.coord2d
 ---@param type df.building_type
 ---@param subtype integer
 ---@param custom integer
 ---@param direction integer
----@return boolean
-function dfhack.buildings.getCorrectSize(size, center, type, subtype, custom, direction) end
+---@return df.coord2d size
+function dfhack.buildings.getCorrectSize(center, type, subtype, custom, direction) end
 
 ---@param coord df.coord
 ---@return df.building

dist/library/modules/items.lua

@@ -15,24 +15,22 @@ dfhack.items = {}
 ---@return df.coord
 function dfhack.items.getPosition(item) end
 
----@param spec_ref df.specific_ref
 ---@param item df.item
 ---@param init_ref boolean|nil
----@return nil
-function dfhack.items.getOuterContainerRef(spec_ref, item, init_ref) end
+---@return df.specific_ref spec_ref
+function dfhack.items.getOuterContainerRef(item, init_ref) end
 
 ---@param item df.item
 ---@param items { [integer]: df.item }
 ---@return nil
 function dfhack.items.getContainedItems(item, items) end
 
----@param mc unknown
 ---@param item df.item
 ---@param building df.building_actual
 ---@param use_mode df.building_item_role_type
 ---@param force_in_building boolean|nil
----@return boolean
-function dfhack.items.moveToBuilding(mc, item, building, use_mode, force_in_building) end
+---@return unknown
+function dfhack.items.moveToBuilding(item, building, use_mode, force_in_building) end
 
 ---@param unit df.unit
 ---@param item_type df.item_type

dist/library/modules/screen.lua

@@ -13,13 +13,12 @@ function dfhack.screen.getMousePixels() end
 ---@return df.coord2d
 function dfhack.screen.getWindowSize() end
 
----@param pen unknown
 ---@param x integer
 ---@param y integer
 ---@param map boolean|nil
 ---@param df::graphic_viewportst::texpos_field number
----@return boolean
-function dfhack.screen.paintTile(pen, x, y, map, df::graphic_viewportst::texpos_field) end
+---@return unknown
+function dfhack.screen.paintTile(x, y, map, df::graphic_viewportst::texpos_field) end
 
 ---@param x integer
 ---@param y integer
@@ -28,30 +27,27 @@ function dfhack.screen.paintTile(pen, x, y, map, df::graphic_viewportst::texpos_
 ---@return unknown
 function dfhack.screen.readTile(x, y, map, df::graphic_viewportst::texpos_field) end
 
----@param pen unknown
 ---@param x integer
 ---@param y integer
 ---@param text string
 ---@param map boolean|nil
----@return boolean
-function dfhack.screen.paintString(pen, x, y, text, map) end
+---@return unknown
+function dfhack.screen.paintString(x, y, text, map) end
 
----@param pen unknown
 ---@param x1 integer
 ---@param y1 integer
 ---@param x2 integer
 ---@param y2 integer
 ---@param map boolean|nil
----@return boolean
-function dfhack.screen.fillRect(pen, x1, y1, x2, y2, map) end
+---@return unknown
+function dfhack.screen.fillRect(x1, y1, x2, y2, map) end
 
----@param pagename string
 ---@param x integer
 ---@param y integer
 ---@param ptile integer
 ---@param pgs integer
----@return boolean
-function dfhack.screen.findGraphicsTile(pagename, x, y, ptile, pgs) end
+---@return unknown
+function dfhack.screen.findGraphicsTile(x, y, ptile, pgs) end
 
 ---@param key df.interface_key
 ---@return integer

dist/library/modules/units.lua

@@ -8,37 +8,34 @@ dfhack.units = {}
 ---@return df.coord
 function dfhack.units.getPosition(unit) end
 
----@param spec_ref df.specific_ref
 ---@param unit df.unit
 ---@param init_ref boolean|nil
----@return nil
-function dfhack.units.getOuterContainerRef(spec_ref, unit, init_ref) end
+---@return df.specific_ref spec_ref
+function dfhack.units.getOuterContainerRef(unit, init_ref) end
 
 ---@param pvec { [integer]: unknown }
 ---@param unit df.unit
 ---@return boolean
 function dfhack.units.getNoblePositions(pvec, unit) end
 
----@param units { [integer]: df.unit }
 ---@param x1 number
 ---@param y1 number
 ---@param z1 number
 ---@param x2 number
 ---@param y2 number
 ---@param z2 number
----@return boolean
-function dfhack.units.getUnitsInBox(units, x1, y1, z1, x2, y2, z2) end
+---@return { [integer]: df.unit }
+function dfhack.units.getUnitsInBox(x1, y1, z1, x2, y2, z2) end
 
 ---@param citizens { [integer]: df.unit }
 ---@param exclude_residents boolean|nil
 ---@param include_insane boolean|nil
 ---@return boolean
 function dfhack.units.getCitizens(citizens, exclude_residents, include_insane) end
 
----@param units { [integer]: df.unit }
 ---@param noble string
----@return boolean
-function dfhack.units.getUnitsByNobleRole(units, noble) end
+---@return { [integer]: df.unit }
+function dfhack.units.getUnitsByNobleRole(noble) end
 
 ---@param unit df.unit
 ---@param trainer_id number

lib/cpp.rb

@@ -154,10 +154,18 @@ def parse_function(match, module_name:, prefix:, function_name:)
         arguments = []
 
         if captures[1]
-          # TODO: Naming convention or actual compiler behaviour?
           arguments = captures[1].split(/,(?![^<>]*>)/).reject.with_index do |arg, index|
             arg[/(&\s*out)|lua_State/] && index.zero?
           end
+
+          # We're accounting for pointers as first arguments _usually_ being a
+          # way of avoiding copy semantics. When these are wrapped as Lua
+          # functions the pointer is returned.
+          if /&\w+/.match(arguments[0])
+            return_type = parse_type(arguments[0].gsub(%r{/\*[^/]+/}, '').gsub(/const\s+|[*&]/, '').strip)
+            arguments.shift(1)
+          end
+
           arguments = arguments.map { |arg| arg.gsub(%r{/\*[^/]+/}, '').gsub(/const\s+|[*&]/, '').strip }
           arguments = arguments&.map do |argument|
             type, _, name = argument.rpartition(' ')