update luals, again. side dish of minor refactoring (#153)

* update luals, again. side dish of minor refactoring

Author: protocol-1903

lib/autorecipes.lua

@@ -208,7 +208,12 @@ local function modify_recipe_tables(item, items_table, previous_item_names, resu
     end
 end
 
---handles all adjustments for each ingredient and result changes in autorecipe
+---handles all adjustments for each ingredient and result changes in autorecipe
+---@param ingredients [data.IngredientPrototype]
+---@param results [data.ProductPrototype]
+---@param previous_ingredients [data.IngredientPrototype]
+---@param previous_results [data.ProductPrototype]
+---@return [data.IngredientPrototype], [data.ProductPrototype]
 local function recipe_item_builder(ingredients, results, previous_ingredients, previous_results)
     local ing_table = table.deepcopy(previous_ingredients)
     local result_table = table.deepcopy(previous_results)
@@ -235,7 +240,7 @@ local function recipe_item_builder(ingredients, results, previous_ingredients, p
 end
 
 ---Provides an interface to quickly build tiered recipes. See recipes-auto-brains.lua for an example
----@param params table
+---@param params {name:RecipeID,category:RecipeCategoryID,subgroup:data.ItemSubGroupID,order:data.Order,main_product?:string,crafting_speed:double,allowed_module_categories:[data.ModuleCategoryID],number_icons:boolean,mats:[{name?:string,ingredients?:[data.IngredientPrototype],results?:[data.ProductPrototype],crafting_speed?:double,tech?:TechnologyID,icon?:data.FileName,icon_size?:integer,icons?:[data.IconData],main_product?:string}]}
 py.autorecipes = function(params)
     local previous_ingredients = {}
     local previous_results = {}

lib/color.lua

@@ -1,12 +1,11 @@
 py.tints = {
+    [0] = {r = 0.5,   g = 0.5,   b = 0.5,   a = 1.0},
     {r = 1.0,   g = 1.0,   b = 0.0,   a = 1.0},
     {r = 1.0,   g = 0.0,   b = 0.0,   a = 1.0},
     {r = 0.223, g = 0.490, b = 0.858, a = 1.0},
     {r = 1.0,   g = 0.0,   b = 1.0,   a = 1.0}
 }
 
-py.tints[0] = {r = 0.5,   g = 0.5,   b = 0.5,   a = 1.0}
-
 py.light_tints = {}
 for i, tint in pairs(py.tints) do
     py.light_tints[i] = {}

lib/control-stage.lua

@@ -10,8 +10,9 @@ require "compound-entities"
 ---Draws a red error icon at the entity's position.
 ---@param entity LuaEntity
 ---@param sprite string
----@param time_to_live integer
----@param blink_interval integer?
+---@param time_to_live integer? default 60 ticks
+---@param blink_interval integer? default 30 ticks
+---@return LuaRenderObject
 py.draw_error_sprite = function(entity, sprite, time_to_live, blink_interval)
     return rendering.draw_sprite {
         sprite = sprite,
@@ -42,7 +43,7 @@ end
 
 ---Randomizes a position by a factor.
 ---@param position MapPosition
----@param factor number?
+---@param factor number? default 1
 ---@return MapPosition
 py.randomize_position = function(position, factor)
     local x = position.x or position[1]
@@ -189,6 +190,7 @@ local si_prefixes = {
 ---formats a number into the amount of energy. Requires 'W' or 'J' as the second parameter
 ---@param energy number
 ---@param watts_or_joules string
+---@return LocalisedString
 py.format_energy = function(energy, watts_or_joules)
     if watts_or_joules == "W" then
         watts_or_joules = "si-unit-symbol-watt"

lib/data-stage.lua

@@ -168,15 +168,16 @@ end
 
 ---Returns a composite icon with a base icon and up to 4 child icons.
 ---The child icons are placed in the corners of the base icon, and can be tinted with a shadow color.
----@param base_prototype_string string
----@param child_top_left string?
----@param child_top_right string?
----@param child_bottom_left string?
----@param child_bottom_right string?
----@param shadow_alpha number?
----@param shadow_scale number?
----@param child_scale number?
----@param shift number?
+---@param base_prototype_string data.FileName
+---@param child_top_left data.FileName?
+---@param child_top_right data.FileName?
+---@param child_bottom_left data.FileName?
+---@param child_bottom_right data.FileName?
+---@param shadow_alpha number? default 0.6
+---@param shadow_scale number? default 0.6
+---@param child_scale number? default 0.5
+---@param shift number? default 10
+---@return [data.IconData]
 function py.composite_icon(base_prototype_string, child_top_left, child_top_right, child_bottom_left, child_bottom_right,
                            shadow_alpha, shadow_scale, child_scale, shift)
     shadow_alpha = shadow_alpha or 0.6
@@ -359,6 +360,7 @@ end
 ---adds a small icon to the top right corner of a recipe
 ---@param recipe data.RecipePrototype
 ---@param corner table
+---@return [data.IconData]
 py.add_corner_icon_to_recipe = function(recipe, corner)
     local icon, icon_size, icons
     local result
@@ -427,9 +429,8 @@ end
 ---Retruns a version of graphics_set with the following properties:
 ---The machine will follow a binary finite state machine (bfsm) to determine the current active animation.
 ---Example (sinter machine): https://github.com/pyanodon/pybugreports/issues/588
----@param states data.VisualState[]
----@param raw_working_visualisations data.WorkingVisualisation[]
----@param shadow data.Animation?
+---@param params {states:[data.VisualState], working_visualisations:[data.WorkingVisualisation], shadow:data.Animation?}
+---@return data.WorkingVisualisations
 py.finite_state_machine_working_visualisations = function(params)
     local states = params.states
 
@@ -500,6 +501,7 @@ end
 
 ---Returns a flipped animation
 ---@param animation4way data.Animation4Way
+---@return data.Animation4Way
 py.flip_4way_animation = function(animation4way)
     local inverse = {
         north = "south",

lib/pipe-connections.lua

@@ -1,11 +1,11 @@
 ---Define pipe connection pipe pictures by coping from an existing entity in the base mod.
 ---@param pictures string
----@param shift_north table?
----@param shift_south table?
----@param shift_west table?
----@param shift_east table?
----@param replacements table?
----@return table
+---@param shift_north Vector?
+---@param shift_south Vector?
+---@param shift_west Vector?
+---@param shift_east Vector?
+---@param replacements {north:data.Sprite,east:data.Sprite,south:data.Sprite,west:data.Sprite}?
+---@return data.Sprite4Way
 py.pipe_pictures = function(pictures, shift_north, shift_south, shift_west, shift_east, replacements)
     local new_pictures = {
         north = shift_north and
@@ -63,14 +63,14 @@ end
 ---@param s boolean?
 ---@param w boolean?
 ---@param e boolean?
----@return table
+---@return data.Sprite4Way
 py.pipe_covers = function(n, s, w, e)
     if (n == nil and s == nil and w == nil and e == nil) then
         n, s, e, w = true, true, true, true
     end
 
-    n =
-        n and {
+    return {
+        north = n and {
             layers = {
                 {
                     filename = "__base__/graphics/entity/pipe-covers/pipe-cover-north.png",
@@ -88,9 +88,8 @@ py.pipe_covers = function(n, s, w, e)
                     draw_as_shadow = true
                 }
             }
-        } or py.empty_image()
-    e =
-        e and {
+        } or py.empty_image(),
+        east = e and {
             layers = {
                 {
                     filename = "__base__/graphics/entity/pipe-covers/pipe-cover-east.png",
@@ -108,9 +107,8 @@ py.pipe_covers = function(n, s, w, e)
                     draw_as_shadow = true
                 }
             }
-        } or py.empty_image()
-    s =
-        s and {
+        } or py.empty_image(),
+        south = s and {
             layers = {
                 {
                     filename = "__base__/graphics/entity/pipe-covers/pipe-cover-south.png",
@@ -128,9 +126,8 @@ py.pipe_covers = function(n, s, w, e)
                     draw_as_shadow = true
                 }
             }
-        } or py.empty_image()
-    w =
-        w and {
+        } or py.empty_image(),
+        west = w and {
             layers = {
                 {
                     filename = "__base__/graphics/entity/pipe-covers/pipe-cover-west.png",
@@ -149,13 +146,13 @@ py.pipe_covers = function(n, s, w, e)
                 }
             }
         } or py.empty_image()
-
-    return {north = n, south = s, east = e, west = w}
+    }
 end
 
 ---Define nice looking pipe pictures based on the space age electromagnetic plant.
 ---These do not come with pipe covers! However there is a frozen variant.
 ---See seaweed-crop.lua in alien life for an example implementation.
+---@return data.Sprite4Way
 py.sexy_pipe_pictures = function()
     local function by_direction(pipe_direction)
         return {
@@ -184,6 +181,7 @@ py.sexy_pipe_pictures = function()
 end
 
 ---Define nice looking pipe frozen pictures based on the space age electromagnetic plant.
+---@return data.Sprite4Way
 py.sexy_pipe_pictures_frozen = function()
     local function by_direction(pipe_direction)
         return {