Ldoc compliant

expcore/common.lua

@@ -48,7 +48,7 @@ local Public = {}
 --- Compare types faster for faster validation of params
 -- @usage type_check('foo','string') -- return true
 -- @usage type_check('foo') -- return false
--- @param v the value to be tested
+-- @tparam any value the value to be tested
 -- @tparam[opt=nil] string test_type the type to test for if not given then it tests for nil
 -- @treturn boolean is v of type test_type
 function Public.type_check(value,test_type)
@@ -57,10 +57,10 @@ end
 
 --- Raises an error if the value is of the wrong type
 -- @usage type_check_error('foo','number','Value must be a number') -- will raise error "Value must be a number"
--- @tparam value any the value that you want to test the type of
--- @tparam test_type string the type that the value should be
--- @tparam error_message string the error message that is returned
--- @tparam level number the level to call the error on (level = 1 means the caller)
+-- @tparam any value the value that you want to test the type of
+-- @tparam string test_type the type that the value should be
+-- @tparam string error_message the error message that is returned
+-- @tparam number level the level to call the error on (level = 1 means the caller)
 -- @treturn boolean true if no error was called
 function Public.type_check_error(value,test_type,error_message,level)
     level = level and level+1 or 2
@@ -69,10 +69,10 @@ end
 
 --- Raises an error when the value is the incorrect type, uses a consistent error message format
 -- @usage param_check('foo','number','repeat_count',2) -- will raise error "Invalid param #02 given to <anon>; repeat_count is not of type number"
--- @tparam value any the value that you want to test the type of
--- @tparam test_type string the type that the value should be
--- @tparam param_name string the name of the param
--- @tparam param_number number the number param it is
+-- @tparam any value the value that you want to test the type of
+-- @tparam string test_type the type that the value should be
+-- @tparam string param_name the name of the param
+-- @tparam number param_number the number param it is
 -- @treturn boolean true if no error was raised
 function Public.param_check(value,test_type,param_name,param_number)
     if not Public.test_type(value,test_type) then
@@ -125,15 +125,15 @@ function Public.player_return(value,colour,player)
 end
 
 --- Writes a table object to a file in json format
--- @tparam path string the path of the file to write include / to use dir
--- @tpatam tbl table the table that will be converted to a json string and wrote to file
+-- @tparam string path the path of the file to write include / to use dir
+-- @tparam table tbl the table that will be converted to a json string and wrote to file
 function Public.write_json(path,tbl)
     game.write_file(path,game.table_to_json(tbl)..'\n',true,0)
 end
 
 --- Calls a require that will not error if the file is not found
 -- @usage local file = opt_require('file.not.present') -- will not cause any error
--- @tparam path string the path that you want to require
+-- @tparam string path the path that you want to require
 -- @return the returns from that file or nil, error if not loaded
 function Public.opt_require(path)
     local success, rtn = pcall(require,path)
@@ -142,9 +142,9 @@ function Public.opt_require(path)
 end
 
 --- Calls a require and returns only the keys given, file must return a table
--- @useage local extract, param_check = ext_require('expcore.common','extract','param_check')
--- @tparam path string the path that you want to require
--- @tparam ... string the name of the keys that you want returned
+-- @usage local extract, param_check = ext_require('expcore.common','extract','param_check')
+-- @tparam string path the path that you want to require
+-- @tparam string ... the name of the keys that you want returned
 -- @return the keys in the order given
 function Public.ext_require(path,...)
     local rtn = require(path)
@@ -159,8 +159,8 @@ end
 -- time will use : separates
 -- string will return a string not a locale string
 -- when a denomination is false it will overflow into the next one
--- @tparam ticks number the number of ticks that represents a time
--- @tparam options table a table of options to use for the format
+-- @tparam number ticks the number of ticks that represents a time
+-- @tparam table options table a of options to use for the format
 -- @treturn string a locale string that can be used
 function Public.format_time(ticks,options)
     -- Sets up the options
@@ -247,10 +247,11 @@ function Public.format_time(ticks,options)
 end
 
 --- Moves items to the position and stores them in the closest entity of the type given
--- @tparam items table items which are to be added to the chests, ['name']=count
--- @tparam[opt=navies] surface LuaSurface the surface that the items will be moved to
--- @tparam[opt={0,0}] position table the position that the items will be moved to {x=100,y=100}
--- @tparam[opt=32] radius number the radius in which the items are allowed to be placed
+-- @tparam table items items which are to be added to the chests, ['name']=count
+-- @tparam[opt=navies] LuaSurface surface the surface that the items will be moved to
+-- @tparam[opt={0,0}] table position the position that the items will be moved to {x=100,y=100}
+-- @tparam[opt=32] number radius the radius in which the items are allowed to be placed
+-- @tparam[opt=iron-chest] string chest_type the chest type that the items should be moved into
 function Public.move_items(items,surface,position,radius,chest_type)
     chest_type = chest_type or 'iron-chest'
     surface = surface or game.surfaces[1]
@@ -438,7 +439,7 @@ function Public.print_colored_grid_value(value, surface, position, offset, immut
 end
 
 --- Clears all flying text entites on a surface
--- @tparam surface LuaSurface the surface to clear
+-- @tparam LuaSurface surface the surface to clear
 function Public.clear_flying_text(surface)
     local entities = surface.find_entities_filtered{name ='flying-text'}
     for _,entity in pairs(entities) do
@@ -458,8 +459,8 @@ end
 
 --- Extracts certain keys from a table
 -- @usage local key_three, key_one = extract({key_one='foo',key_two='bar',key_three=true},'key_three','key_one')
--- @tparam tbl table the table which contains the keys
--- @tparam ... string the names of the keys you want extracted
+-- @tparam table tbl table the which contains the keys
+-- @tparam string ... the names of the keys you want extracted
 -- @return the keys in the order given
 function Public.extract_keys(tbl,...)
     local values = {}
@@ -470,7 +471,7 @@ function Public.extract_keys(tbl,...)
 end
 
 --- Converts a table to an enum
--- @tparam tbl table the table that will be converted
+-- @tparam table tbl table the that will be converted
 -- @treturn table the new table that acts like an enum
 function Public.enum(tbl)
     local rtn = {}
@@ -491,10 +492,10 @@ function Public.enum(tbl)
 end
 
 --- Returns the closest match to the input
--- @tparam options table a table of options for the auto complete
--- @tparam input string the input string that will be completed
--- @tparam[opt=false] use_key boolean when true the keys of options will be used as the options
--- @tparam[opt=false] rtn_key boolean when true the the key will be returned rather than the value
+-- @tparam table options table a of options for the auto complete
+-- @tparam string input string the input that will be completed
+-- @tparam[opt=false] boolean use_key when true the keys of options will be used as the options
+-- @tparam[opt=false] boolean rtn_key when true the the key will be returned rather than the value
 -- @return the list item found that matches the input
 function Public.auto_complete(options,input,use_key,rtn_key)
     local rtn = {}
@@ -511,7 +512,7 @@ function Public.auto_complete(options,input,use_key,rtn_key)
 end
 
 --- Returns all the keys of a table
--- @tparam tbl table the table to get the keys of
+-- @tparam table tbl table the to get the keys of
 -- @treturn table an array of the table keys
 function Public.table_keys(tbl)
     local rtn = {}
@@ -522,7 +523,7 @@ function Public.table_keys(tbl)
 end
 
 --- Returns all the values of a table
--- @tparam tbl table the table to get the values of
+-- @tparam table tbl table the to get the values of
 -- @treturn table an array of the table values
 function Public.table_values(tbl)
     local rtn = {}
@@ -558,8 +559,8 @@ function Public.table_keysort(tbl)
 end
 
 --- Returns a message with valid chat tags to change its colour
--- @tparam message string the message that will be in the output
--- @tparam color table a color which contains r,g,b as its keys
+-- @tparam string message the message that will be in the output
+-- @tparam table color a color which contains r,g,b as its keys
 -- @treturn string the message with the color tags included
 function Public.format_chat_colour(message,color)
     color = color or Colours.white
@@ -568,8 +569,8 @@ function Public.format_chat_colour(message,color)
 end
 
 --- Returns a message with valid chat tags to change its colour, using localization
--- @tparam message ?string|table the message that will be in the output
--- @tparam color table a color which contains r,g,b as its keys
+-- @tparam ?string|table message the message that will be in the output
+-- @tparam table color a color which contains r,g,b as its keys
 -- @treturn table the message with the color tags included
 function Public.format_chat_colour_localized(message,color)
     color = color or Colours.white
@@ -578,8 +579,8 @@ function Public.format_chat_colour_localized(message,color)
 end
 
 --- Returns the players name in the players color
--- @tparam player LuaPlayer the player to use the name and color of
--- @tparam[opt=false] raw_string boolean when true a string is returned rather than a localized string
+-- @tparam LuaPlayer player the player to use the name and color of
+-- @tparam[opt=false] boolean raw_string when true a is returned rather than a localized string
 -- @treturn table the players name with tags for the players color
 function Public.format_chat_player_name(player,raw_string)
     player = Game.get_player_from_any(player)