Add comments and use safe_name for params

Author: vallode

dist/library/structures/df.art.lua

@@ -36,7 +36,7 @@ function art_image_element:read_file(file, loadversion) end
 ---@return df.art_image_element_type
 function art_image_element:getType() end
 
----@param ID number
+---@param ID number race, item type, plant ID, or shape ID
 function art_image_element:setID(ID) end
 
 ---@return df.art_image_element
@@ -51,7 +51,7 @@ function art_image_element:getSymbol(sym, anon_0) end
 ---@param useName boolean
 function art_image_element:getName1(name, useThe, useName) end
 
----@param name string
+---@param name string seems to return like getName1 but with useName true
 ---@param anon_0 boolean
 function art_image_element:getName2(name, anon_0) end
 

dist/library/structures/df.buildings.lua

@@ -631,7 +631,7 @@ function building:uncategorize() end
 ---@return number
 function building:getBaseValue() end
 
----@param new_state number
+---@param new_state number 0 = active/open, 1 = inactive/closed
 function building:setTriggerState(new_state) end
 
 ---@return boolean
@@ -671,7 +671,7 @@ function building:getDrawExtents(buffer) end
 
 ---@param curtick integer
 ---@param buffer df.building_drawbuffer
----@param z_offset number
+---@param z_offset number building_wellst only
 function building:drawBuilding(curtick, buffer, z_offset) end
 
 ---@return number

dist/library/structures/df.history.lua

@@ -2483,36 +2483,36 @@ local history_event
 ---@return df.history_event_type
 function history_event:getType() end
 
----@param entity1 number
----@param entity2 number
+---@param entity1 number References: `historical_entity`
+---@param entity2 number References: `historical_entity`
 ---@return number
 function history_event:getWarStatus(entity1, entity2) end
 
----@param entity1 number
----@param entity2 number
+---@param entity1 number References: `historical_entity`
+---@param entity2 number References: `historical_entity`
 ---@return number
 function history_event:getAngerModifier(entity1, entity2) end
 
----@param entity1 number
----@param entity2 number
+---@param entity1 number References: `historical_entity`
+---@param entity2 number References: `historical_entity`
 ---@return number
 function history_event:getHappinessModifier(entity1, entity2) end
 
----@param entity1 number
----@param entity2 number
----@param site number
+---@param entity1 number References: `historical_entity`
+---@param entity2 number References: `historical_entity`
+---@param site number References: `world_site`
 ---@return boolean
 function history_event:madeFirstContact(entity1, entity2, site) end
 
----@param killer number
+---@param killer number References: `historical_figure`
 ---@return number
 function history_event:getKilledHistfigID(killer) end
 
----@param victim number
+---@param victim number References: `historical_figure`
 ---@return boolean
 function history_event:wasHistfigKilled(victim) end
 
----@param histfig number
+---@param histfig number References: `historical_figure`
 ---@return boolean
 function history_event:wasHistfigRevived(histfig) end
 
@@ -2538,51 +2538,51 @@ function history_event:getRelatedLayerIDs(vec) end
 ---@param vec DFPointer<integer>
 function history_event:getRelatedEntityIDs(vec) end
 
----@param histfig number
+---@param histfig number References: `historical_figure`
 ---@return boolean
 function history_event:isRelatedToHistfigID(histfig) end
 
----@param site number
+---@param site number References: `world_site`
 ---@return boolean
 function history_event:isRelatedToSiteID(site) end
 
----@param site number
----@param structure number
+---@param site number References: `world_site`
+---@param structure number References: `abstract_building`
 ---@return boolean
 function history_event:isRelatedToSiteStructure(site, structure) end
 
----@param artifact number
+---@param artifact number References: `artifact_record`
 ---@return boolean
 function history_event:isRelatedToArtifactID(artifact) end
 
----@param region number
+---@param region number References: `world_region`
 ---@return boolean
 function history_event:isRelatedToRegionID(region) end
 
----@param region number
+---@param region number References: `world_underground_region`
 ---@return boolean
 function history_event:isRelatedToLayerID(region) end
 
----@param agreement number
+---@param agreement number References: `agreement`
 ---@return boolean
 function history_event:isRelatedToAgreementID(agreement) end
 
----@param entity number
+---@param entity number References: `historical_entity`
 ---@return boolean
 function history_event:isRelatedToEntityID(entity) end
 
 ---@param str string
----@param context df.history_event_context
+---@param context df.history_event_context "In x, some event happened"
 function history_event:getSentence(str, context) end
 
 ---@param str string
----@param context df.history_event_context
+---@param context df.history_event_context "the happening of some event"
 function history_event:getPhrase(str, context) end
 
 ---@param image df.art_image
 function history_event:populateArtImage(image) end
 
----@param histfig number
+---@param histfig number References: `historical_figure`
 ---@return boolean
 function history_event:isChangedHistfigID(histfig) end
 

dist/library/structures/df.interaction.lua

@@ -194,8 +194,8 @@ function interaction_effect:write_file(file) end
 function interaction_effect:read_file(file, loadversion) end
 
 ---@param target df.unit
----@param anon_0 DFPointer<integer>
----@param anon_1 boolean
+---@param anon_0 DFPointer<integer> has pointer-vector at offset 0x10
+---@param anon_1 boolean only used by animate
 function interaction_effect:activateOnUnit(target, anon_0, anon_1) end
 
 ---@param target df.item

dist/library/structures/df.itemimprovements.lua

@@ -107,7 +107,7 @@ function itemimprovement:isDecoration() end
 ---@return number
 function itemimprovement:getDyeValue(caravan) end
 
----@param shape number
+---@param shape number References: `descriptor_shape`
 function itemimprovement:setShape(shape) end
 
 

dist/library/structures/df.items.lua

@@ -634,7 +634,7 @@ function item:isScrew() end
 ---@return boolean
 function item:isBuildMat() end
 
----@param anon_0 number
+---@param anon_0 number 1 fire, 2 magma
 ---@return boolean
 function item:isTemperatureSafe(anon_0) end
 
@@ -679,12 +679,12 @@ function item:isMatchingAmmoItem(anon_0) end
 ---@param subid DFPointer<integer>
 function item:getImageRef(id, subid) end
 
----@param civ_id number
----@param site_id number
+---@param civ_id number References: `historical_entity`
+---@param site_id number References: `world_site`
 function item:getImageCivSite(civ_id, site_id) end
 
----@param civ_id number
----@param site_id number
+---@param civ_id number References: `historical_entity`
+---@param site_id number References: `world_site`
 function item:setImageCivSite(civ_id, site_id) end
 
 ---@param level number
@@ -741,7 +741,7 @@ function item:getVolume() end
 ---@param unit df.unit
 ---@param mat_type number
 ---@param mat_index number
----@param shape number
+---@param shape number References: `descriptor_shape`
 ---@param force_quality number
 ---@param civ df.historical_entity
 ---@param site df.world_site
@@ -811,9 +811,9 @@ function item:isAnimal() end
 ---@return df.item_quality
 function item:assignQuality(maker, job_skill) end
 
----@param maker df.unit
+---@param maker df.unit called by assignQuality
 ---@param job_skill df.job_skill
----@param skill_roll number
+---@param skill_roll number preferences add 10 to this, need 55 to roll masterworks
 ---@return df.item_quality
 function item:assignQuality2(maker, job_skill, skill_roll) end
 
@@ -949,11 +949,11 @@ function item:isNotHeld() end
 ---@return boolean
 function item:isSplittable() end
 
----@param anon_0 df.historical_entity
+---@param anon_0 df.historical_entity add default thread improvement to items made of cloth
 function item:addDefaultThreadImprovement(anon_0) end
 
 ---@param anon_0 df.item
----@param anon_1 df.historical_entity
+---@param anon_1 df.historical_entity add a specific thread improvement to items made of cloth
 function item:addThreadImprovement(anon_0, anon_1) end
 
 function item:propagateUnitRefs() end
@@ -980,36 +980,36 @@ function item:isAutoClean() end
 ---@param x number
 ---@param y number
 ---@param z number
----@param local boolean
+---@param _local boolean
 ---@param contained boolean
 ---@return boolean
-function item:setTemperatureFromMapTile(x, y, z, local, contained) end
+function item:setTemperatureFromMapTile(x, y, z, _local, contained) end
 
----@param local boolean
+---@param _local boolean
 ---@param contained boolean
 ---@return boolean
-function item:setTemperatureFromMap(local, contained) end
+function item:setTemperatureFromMap(_local, contained) end
 
 ---@param temp integer
----@param local boolean
+---@param _local boolean
 ---@param contained boolean
 ---@return boolean
-function item:setTemperature(temp, local, contained) end
+function item:setTemperature(temp, _local, contained) end
 
----@param local boolean
+---@param _local boolean
 ---@param contained boolean
 ---@param adjust boolean
 ---@param multiplier number
 ---@return boolean
-function item:updateTempFromMap(local, contained, adjust, multiplier) end
+function item:updateTempFromMap(_local, contained, adjust, multiplier) end
 
 ---@param temp integer
----@param local boolean
+---@param _local boolean
 ---@param contained boolean
 ---@param adjust boolean
 ---@param multiplier number
 ---@return boolean
-function item:updateTemperature(temp, local, contained, adjust, multiplier) end
+function item:updateTemperature(temp, _local, contained, adjust, multiplier) end
 
 ---@return boolean
 function item:updateFromWeather() end
@@ -1054,7 +1054,7 @@ function item:getProjectileSize() end
 function item:isImprovable(anon_0, mat_type, mat_index) end
 
 ---@param item_quality number
----@param unk1 number
+---@param unk1 number when 0, set item_rockst sharpness to 0
 function item:setSharpness(item_quality, unk1) end
 
 ---@return number
@@ -1132,7 +1132,7 @@ function item:isImproved() end
 function item:getMagic() end
 
 ---@param anon_0 string
----@param plurality number
+---@param plurality number 0 = prickle berries [2], 1 = prickle berry, 2 = prickle berries
 function item:getItemDescription(anon_0, plurality) end
 
 ---@param anon_0 string
@@ -1254,7 +1254,7 @@ function item:getAbsorption() end
 ---@return boolean
 function item:isGemMaterial() end
 
----@param shape number
+---@param shape number References: `descriptor_shape`
 function item:setGemShape(shape) end
 
 ---@return boolean

dist/library/structures/df.raws.lua

@@ -12,15 +12,15 @@
 ---@field hist_fig_to_creature_map DFNumberVector unordered_map<int32_t,int32_t>
 local creature_handler
 
----@param creature_index number
----@param caste_index number
+---@param creature_index number References: `creature_raw`
+---@param caste_index number References: `caste_raw`
 ---@param alt boolean
 ---@param soldier boolean
 ---@return integer
 function creature_handler:getTile(creature_index, caste_index, alt, soldier) end
 
----@param creature_index number
----@param caste_index number
+---@param creature_index number References: `creature_raw`
+---@param caste_index number References: `caste_raw`
 ---@return integer
 function creature_handler:getGlowTile(creature_index, caste_index) end
 

dist/library/structures/df.reaction-raws.lua

@@ -197,18 +197,18 @@ function reaction_reagent:getType() end
 function reaction_reagent:resolveTokens(reactionID) end
 
 ---@param anon_0 df.item
----@param index number
+---@param index number References: `reaction`
 ---@return boolean
 function reaction_reagent:matchesRoot(anon_0, index) end
 
 ---@param anon_0 df.item
----@param anon_1 df.reaction
----@param index number
+---@param anon_1 df.reaction or maybe reaction code string ref
+---@param index number References: `reaction`
 ---@return boolean
 function reaction_reagent:matchesChild(anon_0, anon_1, index) end
 
 ---@param anon_0 string
----@param index number
+---@param index number References: `reaction`
 function reaction_reagent:getDescription(anon_0, index) end
 
 ---@return boolean
@@ -299,10 +299,10 @@ function reaction_product:resolveTokens(reactionID) end
 ---@param in_items DFPointer<integer>
 ---@param quantity number
 ---@param skill df.job_skill
----@param job_quality number
+---@param job_quality number gets +10 for matching preferences, uses cutoffs 23/30/35/45/55 for Well/Fine/Superior/Exceptional/Masterwork
 ---@param entity df.historical_entity
 ---@param site df.world_site
----@param unk4 DFPointer<integer>
+---@param unk4 DFPointer<integer> only used when making improvements
 function reaction_product:produce(maker, out_products, out_items, in_reag, in_items, quantity, skill, job_quality, entity, site, unk4) end
 
 ---@param desc string

lib/lua_ls.rb

@@ -44,6 +44,15 @@ def class(name, parent = nil, comment: nil, exact: false)
         annotation.join
       end
 
+      def param(name, type, comment: nil)
+        annotation = ['---@param']
+        annotation << " #{safe_name(name)}"
+        annotation << " #{type}"
+        annotation << " #{comment}" if comment
+        annotation << "\n"
+        annotation.join
+      end
+
       def field(name, type, comment = nil)
         annotation = ['---@field']
         annotation << " #{safe_name(name)}"