Support top level comments in cpp files

Author: vallode

dist/library/modules/buildings.lua

@@ -25,6 +25,7 @@ function dfhack.buildings.findCivzonesAt(pvec, pos) end
 ---@return df.coord2d size
 function dfhack.buildings.getCorrectSize(center, type, subtype, custom, direction) end
 
+-- returns building of pen/pit at cursor position (NULL if nothing found)
 ---@param coord df.coord
 ---@return df.building
 function dfhack.buildings.findPenPitAt(coord) end

dist/library/modules/gui.lua

@@ -70,6 +70,7 @@ function dfhack.gui.pauseRecenter(x, y, z, pause) end
 ---@return boolean
 function dfhack.gui.revealInDwarfmodeMap(x, y, z, center, highlight) end
 
+-- returns the map coordinates that the mouse cursor is over
 ---@param allow_out_of_bounds boolean|nil
 ---@return df.coord
 function dfhack.gui.getMousePos(allow_out_of_bounds) end

dist/library/modules/items.lua

@@ -73,6 +73,7 @@ function dfhack.items.getHolderBuilding(item) end
 ---@return df.unit
 function dfhack.items.getHolderUnit(item) end
 
+-- It's not impossible the functionality of this operation is provided by one of the unmapped item functions.
 ---@param item df.item
 ---@return string
 function dfhack.items.getBookTitle(item) end
@@ -138,6 +139,7 @@ function dfhack.items.canTradeAnyWithContents(item) end
 ---@return boolean
 function dfhack.items.markForTrade(item, depot) end
 
+-- (i.e., returning true if and only if the item has a "designate for melting" button in game)
 ---@param item df.item
 ---@param game_ui boolean|nil
 ---@return boolean

dist/library/modules/military.lua

@@ -4,6 +4,7 @@
 ---@class dfhack.military
 dfhack.military = {}
 
+-- could be extended straightforwardly by passing in entity
 ---@param assignment_id number
 ---@return df.squad
 function dfhack.military.makeSquad(assignment_id) end

dist/library/modules/screen.lua

@@ -10,9 +10,11 @@
 ---@field _doSimulateInput function
 dfhack.screen = {}
 
+-- returns ui grid coordinates, even if the game map is scaled differently
 ---@return df.coord2d
 function dfhack.screen.getMousePos() end
 
+-- returns the screen pixel coordinates
 ---@return df.coord2d
 function dfhack.screen.getMousePixels() end
 

dist/library/modules/units.lua

@@ -19,6 +19,7 @@ function dfhack.units.getOuterContainerRef(unit, init_ref) end
 ---@return boolean
 function dfhack.units.getNoblePositions(pvec, unit) end
 
+-- returns index of creature actually read or -1 if no creature can be found
 ---@param x1 number
 ---@param y1 number
 ---@param z1 number
@@ -74,14 +75,17 @@ function dfhack.units.isResident(unit, include_insane) end
 ---@return boolean
 function dfhack.units.isFortControlled(unit) end
 
+-- (don't try to pasture/slaughter random untame animals)
 ---@param unit df.unit
 ---@return boolean
 function dfhack.units.isOwnCiv(unit) end
 
+-- check if creature belongs to the player's group
 ---@param unit df.unit
 ---@return boolean
 function dfhack.units.isOwnGroup(unit) end
 
+-- (in combination with check for civ helps to filter out own dwarves)
 ---@param unit df.unit
 ---@return boolean
 function dfhack.units.isOwnRace(unit) end
@@ -162,10 +166,12 @@ function dfhack.units.isTrainableWar(unit) end
 ---@return boolean
 function dfhack.units.isTrained(unit) end
 
+-- check for profession "hunting creature"
 ---@param unit df.unit
 ---@return boolean
 function dfhack.units.isHunter(unit) end
 
+-- check for profession "war creature"
 ---@param unit df.unit
 ---@return boolean
 function dfhack.units.isWar(unit) end
@@ -178,6 +184,7 @@ function dfhack.units.isTame(unit) end
 ---@return boolean
 function dfhack.units.isTamable(unit) end
 
+-- seems to be the only way to really tell if it's completely safe to autonestbox it (training can revert)
 ---@param unit df.unit
 ---@return boolean
 function dfhack.units.isDomesticated(unit) end
@@ -238,6 +245,7 @@ function dfhack.units.isForest(unit) end
 ---@return boolean
 function dfhack.units.isMischievous(unit) end
 
+-- check if unit is marked as available for adoption
 ---@param unit df.unit
 ---@return boolean
 function dfhack.units.isAvailableForAdoption(unit) end
@@ -472,6 +480,7 @@ function dfhack.units.getRaceName(unit) end
 ---@return string
 function dfhack.units.getRaceNamePlural(unit) end
 
+-- get race name by id or unit pointer
 ---@param id number
 ---@return string
 function dfhack.units.getRaceNameById(id) end

lib/cpp.rb

@@ -75,9 +75,8 @@ def parse_cpp_modules(entry_point)
               function_name = name.gsub(/"/, '').strip
               signature_name = signature.gsub(/"/, '').strip
 
-              module_file[/^(?:static\s)?(?:DFHACK_EXPORT\s)?(\S+).*?#{namespace}#{signature_name.gsub(
-                /#{module_name}_/, ''
-              )}\s?\(([^)]+)?\)/]
+              cleaned_signature_name = signature_name.gsub(/#{module_name}_/, '')
+              module_file[/^(?:static\s)?(?:DFHACK_EXPORT\s)?(\S+).*?#{namespace}#{cleaned_signature_name}\s?\(([^)]+)?\)/]
               next if Regexp.last_match
 
               file[/^(?:static\s)?(?:DFHACK_EXPORT\s)?(\S+).*?#{signature_name}\s?\(([^)]+)?\)/]
@@ -97,9 +96,8 @@ def parse_cpp_modules(entry_point)
               function_name = name.gsub(/"/, '').strip
               signature_name = signature.gsub(/"/, '').strip
 
-              module_file[/^(?:static\s)?(?:DFHACK_EXPORT\s)?(\S+).*?#{namespace}#{signature_name.gsub(
-                /#{module_name}_/, ''
-              )}\s?\(([^)]+)?\)/]
+              cleaned_signature_name = signature_name.gsub(/#{module_name}_/, '')
+              module_file[%r{(//.*\R)?^(?:static\s)?(?:DFHACK_EXPORT\s)?(\S+).*?#{namespace}#{cleaned_signature_name}\s?\(([^)]+)?\)}]
               next unless Regexp.last_match
 
               functions << DFHackLuaDefinitions::CPP.parse_function(Regexp.last_match, module_name:, prefix:,
@@ -110,7 +108,7 @@ def parse_cpp_modules(entry_point)
               function_name = Regexp.last_match(1) if function_name =~ /,\s?(\S+)/
               signature = "#{namespace}#{function_name}"
 
-              module_file[/^(?:static\s)?(?:DFHACK_EXPORT\s)?(\S+).*?#{signature}\s?\(([^)]+)?\)/]
+              module_file[%r{(//.*\R)?^(?:static\s)?(?:DFHACK_EXPORT\s)?(\S+).*?#{signature}\s?\(([^)]+)?\)}]
 
               next unless Regexp.last_match
 
@@ -156,11 +154,16 @@ def parse_function(match, module_name:, prefix:, function_name:)
         annotation = []
 
         captures = match.captures
-        return_type = parse_type(captures[0])
+        if captures[0]
+          comment = captures[0].gsub(%r{^//\s*}, '').strip
+          annotation << DFHackLuaDefinitions::Annotation.multiline_comment(comment)
+        end
+
+        return_type = parse_type(captures[1])
         arguments = []
 
-        if captures[1]
-          arguments = captures[1].split(/,(?![^<>]*>)/).reject.with_index do |arg, index|
+        if captures[2]
+          arguments = captures[2].split(/,(?![^<>]*>)/).reject.with_index do |arg, index|
             arg[/(&\s*out)|lua_State/] && index.zero?
           end