Ldoc compliant

This commit is contained in:
Cooldude2606
2019-05-29 22:24:04 +01:00
parent 53f9c51c0e
commit e187059ae0
94 changed files with 15315 additions and 479 deletions

View File

@@ -24,7 +24,7 @@ function commands.add_middleware(callback) if not is_type(callback,'function') t
-- @field commands.data
-- @usage commands.command_name -- returns command data
-- @usage commands.data -- returns all data
-- @tparam ?string|table|event key the command that will be returned: string is the name, table is the command data, event is event from add_command
-- @tparam string table ?string|table|event key the command that will be returned: is the name, is the command data, event is event from add_command
-- @treturn table the command data
setmetatable(commands,{
__index=function(tbl,key) return is_type(key,'table') and (key.command and rawget(commandDataStore,key.name) or key) or key == 'data' and commandDataStore or rawget(commandDataStore,key) end
@@ -242,9 +242,9 @@ end
--- Used to define commands
-- @usage --see examples in file
-- @tparam string name the name of the command
-- @tparam[opt='No Description'] string description the description of the command
-- @tparam[opt=an infinite string] table inputs a table of the inputs to be used, last index being true makes the last parameter open ended (longer than one word)
-- @tparam function callback the function to call on the event
-- @tparam[opt='No string Description'] description the description of the command
-- @tparam[opt=an table table infinite string] inputs a of the inputs to be used, last index being true makes the last parameter open ended (longer than one word)
-- @tparam function function callback the to call on the event
commands.add_command = function(name, description, inputs, callback)
if commands[name] then error('That command is already registered',2) end
if not is_type(name,'string') then error('Command name has not been given') end

View File

@@ -40,7 +40,7 @@ _GroupSelfRef=Group
--- Defines a new instance of a group
-- @usage Group.define{name='foo',disallow={'edit_permission_group','delete_permission_group','add_permission_group'}} -- returns new group
-- @usage Group{name='foo',disallow={'edit_permission_group','delete_permission_group','add_permission_group'}} -- returns new group
-- @tparam table obj contains string name and table disallow of defines.input_action
-- @tparam string table table obj contains name and disallow of defines.input_action
-- @treturn Group the group which has been made
function Group.define(obj)
if not type_error(game,nil,'Cant define Group during runtime.') then return end

View File

@@ -48,7 +48,7 @@ end
--- Adds a label that is centered
-- @usage Gui.centered_label(frame, 'Hello, world!')
-- @tparam LuaGuiElement frame the parent frame to add the label to
-- @tparam string string the string that the label will have
-- @tparam string string string the that the label will have
function Gui.centered_label(frame, string)
local flow = frame.add {frame = 'flow'}
local flow_style = flow.style

View File

@@ -28,7 +28,7 @@ inputs.events = {
--- Sets the input to trigger on an certain event
-- @usage button:on_event(defines.events.on_gui_click,player_return)
-- @param event the event to raise callback on | can be number of the event | can be a key of inputs.events
-- @tparam function callback the function you want to run on the event
-- @tparam function function callback the you want to run on the event
-- @treturn table returns self so you can chain together
function inputs._prototype:on_event(event,callback)
if not is_type(callback,'function') then return self end
@@ -311,8 +311,8 @@ end
-- @tparam string orientation direction of the slider
-- @tparam number min the lowest number
-- @tparam number max the highest number
-- @tparam function start_callback either a number or a function to return a number
-- @tparam function callback the function to be called on value_changed function(player,value,percent,element)
-- @tparam number function function start_callback either a or a to return a number
-- @tparam function function callback the to be called on value_changed function(player,value,percent,element)
-- @treturn table the slider object that was made, to allow a custom error event if wanted
function inputs.add_slider(name,orientation,min,max,start_callback,callback)
local slider = inputs.add{

View File

@@ -38,7 +38,7 @@ end)
-- @tparam string name the name of the button
-- @tparam string caption can be a sprite path or text to show
-- @tparam string tooltip the help to show for the button
-- @tparam function callback the function which is called on_click
-- @tparam function function callback the which is called on_click
-- @treturn table the button object that was made, calling the returned value will draw the toolbar button added
function toolbar.add(name,caption,tooltip,callback)
verbose('Created Toolbar Button: '..name)

View File

@@ -80,7 +80,7 @@ function Role.set_preassign(tbl) if game then global.preassign = tbl else Role.p
--- Defines a new instance of a role
-- @usage Role.define{name='Root',short_hand='Root',tag='[Root]',group='Root',colour={r=255,b=255,g=255},is_root=true,allow={}} -- returns new role
-- @usage Role{name='Root',short_hand='Root',tag='[Root]',group='Root',colour={r=255,b=255,g=255},is_root=true,allow={}} -- returns new role
-- @tparam table obj contains the strings: name,short_hand,tag a table called allow a table called colour and a pointer to a permission group
-- @tparam table table obj contains the strings: name,short_hand,tag a called allow a table called colour and a pointer to a permission group
-- @treturn Role the role which has been made
function Role.define(obj)
if not type_error(game,nil,'Cant define Role during runtime.') then return end
@@ -127,7 +127,7 @@ end
-- @usage Role.assign(player,'Root')
-- @usage Role.assign(player,{'Root','Foo'})
-- @tparam ?LuaPlayer|pointerToPlayer player the player to assign the role to
-- @tparam ?string|role|table the role to add the player to, if its a table then it will act recursively though the table
-- @tparam table ?string|role|table the role to add the player to, if its a then it will act recursively though the table
-- @tparam[opt='<server>'] ?LuaPlayer|pointerToPlayer by_player the player who assigned the roles to the player
-- @tparam[opt] table batch this is used internally to prevent multiple event calls, contains {role_index_in_batch,batch}
-- @treturn boolean was the player assigned the roles
@@ -153,7 +153,7 @@ end
--- Used to remove a player from a role(s)
-- @usage Role.unassign(player,'Root')
-- @tparam ?LuaPlayer|pointerToPlayer player the player to unassign the role to
-- @tparam ?string|role|table role the role to remove the player from, if its a table then it will act recursively though the table
-- @tparam table ?string|role|table role the role to remove the player from, if its a then it will act recursively though the table
-- @tparam[opt='<server>'] ?LuaPlayer|pointerToPlayer by_player the player who unassigned the roles from the player
-- @tparam[opt] table batch this is used internally to prevent multiple event calls
-- @treturn boolean was the player unassigned the roles
@@ -179,7 +179,7 @@ end
--- Returns the highest role given in a list, if a player is passed then it returns the highest role of the player
-- @usage Role.get_highest{'Root','Admin','Mod'} -- returns Root (given that root is highest)
-- @usage Role.get_highest(player) -- returns the players highest role
-- @tparam ?table|LuaPlayer|pointerToPlayer options table of options or a player
-- @tparam table ?table|LuaPlayer|pointerToPlayer options of options or a player
-- @treturn role the highest role given in the options
function Role.get_highest(options)
local player = Game.get_player(options)
@@ -199,7 +199,7 @@ end
-- @usage Role.revert(player) -- reverts the last change to the players roles
-- @tparam ?LuaPlayer|pointerToPlayer player the player to revert the changes of
-- @tparam[opt] ?LuaPlayer|pointerToPlayer the player who preformed the role revert
-- @tparam[opt=1] count the number of reverts to do, if 0 all changes cached are reverted
-- @tparam[opt=1] number count the of reverts to do, if 0 all changes cached are reverted
-- @treturn number the number of changes that occurred
function Role.revert(player,by_player,count)
player = Game.get_player(player)
@@ -224,7 +224,7 @@ end
--- Adds a flag which can be set on roles; these flags act as a quick way to access general role changes
-- @usage Role.add_flag('is_admin',function(player,state) player.admin = state end) -- the function is passed player and if the flag is true or false
-- @tparam string flag the name of the flag that is being added
-- @tparam[opt] function callback the function(player,state) which is called when a player loses or gains a flag, if nil no function is called
-- @tparam[opt] function function callback the function(player,state) which is called when a player loses or gains a flag, if nil no is called
function Role.add_flag(flag,callback)
if not type_error(flag,'string','Invalid argument #1 to Role.add_flag, flag is not a string.') then return end
if callback and not type_error(callback,'function','Invalid argument #2 to Role.add_flag, callback is not a function.') then return end

View File

@@ -12,7 +12,7 @@ local ExpLib = {}
--- Loads a table into _G even when sandboxes; will not overwrite values or append to tables; will not work during runtime to avoid desyncs
-- @usage unpack_to_G{key1='foo',key2='bar'}
-- @tparam table tbl table to be unpacked
-- @tparam table table tbl to be unpacked
function ExpLib.unpack_to_G(tbl)
if not type(tbl) == 'table' or game then return end
for key,value in pairs(tbl) do
@@ -60,9 +60,9 @@ end
--- Creates a table that will act like a string and a function
-- @usage add_metatable({},function) -- returns table
-- @tparam table tbl the table that will have its metatable set
-- @tparam[opt=tostring] function callback the function that will be used for the call
-- @tparam[opt=table.tostring] ?function|string string a function that resolves to a string or a string
-- @tparam table table tbl the that will have its metatable set
-- @tparam[opt=tostring] function function callback the that will be used for the call
-- @tparam[opt=table.tostring] function string string ?function|string a that resolves to a or a string
-- @treturn table the new table with its metatable set
function ExpLib.add_metatable(tbl,callback,string)
if not ExpLib.is_type(tbl,'table') then error('No table given to add_metatable',2) end
@@ -98,7 +98,7 @@ end
--- A specialised version of type_error to test for self
-- @usage self_test(self,'Object','get_name')
-- @tparam table self the table that is the object
-- @tparam table table self the that is the object
-- @tparam string prototype_name the name of the class
-- @tparam string function_name the name of the function
function ExpLib.self_test(self,prototype_name,function_name)
@@ -240,7 +240,7 @@ end
--- Returns a table in a form able to be read as a table
-- @usage table.tostring{k1='foo',k2='bar'} -- return '{["k1"]="foo",["k2"]="bar"}'
-- @tparam table tbl table to convert
-- @tparam table table tbl to convert
-- @treturn string the converted table
function table.tostring(tbl)
if type(tbl) ~= 'table' then return tostring(tbl) end
@@ -260,7 +260,7 @@ end
--- Similar to table.tostring but converts a lua table to a json one
-- @usage table.json{k1='foo',k2='bar'} -- return '{"k1":"foo","k2":"bar"}'
-- @tparam table lua_table the table to convert
-- @tparam table table lua_table the to convert
-- @treturn string the table in a json format
function table.json(lua_table)
--if game and game.table_to_json then return game.table_to_json(lua_table) end
@@ -288,8 +288,8 @@ end
--- Returns the closest match to a key
-- @usage table.autokey({foo=1,bar=2},'f') -- return 1
-- @tparam table tbl the table that will be searched
-- @tparam string str the string that will be looked for in the keys
-- @tparam table table tbl the that will be searched
-- @tparam string string str the that will be looked for in the keys
function table.autokey(tbl,str)
if not ExpLib.is_type(str,'string') then return end
local _return = {}
@@ -301,7 +301,7 @@ end
--- Returns the list is a sorted way that would be expected by people (this is by key)
-- @usage tbl = table.alphanumsort(tbl)
-- @tparam table tbl the table to be sorted
-- @tparam table table tbl the to be sorted
-- @treturn table the sorted table
function table.alphanumsort(tbl)
local o = table.keys(tbl)
@@ -317,7 +317,7 @@ end
--- Returns the list is a sorted way that would be expected by people (this is by key) (faster alterative than above)
-- @usage tbl = table.alphanumsort(tbl)
-- @tparam table tbl the table to be sorted
-- @tparam table table tbl the to be sorted
-- @treturn table the sorted table
function table.keysort(tbl)
local o = table.keys(tbl,true)

View File

@@ -177,7 +177,7 @@ end
--- Get a color table with a hexadecimal string.
-- Optionally provide the value for the alpha channel.
-- @tparam string hex hexadecimal color string (#ffffff, not #fff)
-- @tparam string string hex hexadecimal color (#ffffff, not #fff)
-- @tparam[opt=1] float alpha the alpha value to set; such that ***[ 0 &#8924; value &#8924; 1 ]***
-- @treturn a color table with RGB converted from Hex and with alpha
function Color.from_hex(hex, alpha)

View File

@@ -36,7 +36,7 @@ end
--- Print msg if specified var evaluates to false.
-- @tparam Mixed var variable to evaluate
-- @tparam[opt="missing value"] string msg message
-- @tparam[opt="missing string value"] msg message
function Game.fail_if_missing(var, msg)
if not var then
error(msg or "Missing value", 3)

View File

@@ -5,14 +5,14 @@
-- luacheck: globals string (Allow mutating string)
--- Returns a copy of the string with any leading or trailing whitespace from the string removed.
-- @tparam string s the string to remove leading or trailing whitespace from
-- @tparam string string s the to remove leading or trailing whitespace from
-- @treturn string a copy of the string without leading or trailing whitespace
function string.trim(s)
return (s:gsub("^%s*(.-)%s*$", "%1"))
end
--- Tests if a string starts with a given substring.
-- @tparam string s the string to check for the start substring
-- @tparam string string s the to check for the start substring
-- @tparam string start the substring to test for
-- @treturn boolean true if the start substring was found in the string
function string.starts_with(s, start)
@@ -20,7 +20,7 @@ function string.starts_with(s, start)
end
--- Tests if a string ends with a given substring.
-- @tparam string s the string to check for the end substring
-- @tparam string string s the to check for the end substring
-- @tparam string ends the substring to test for
-- @treturn boolean true if the end substring was found in the string
function string.ends_with(s, ends)
@@ -28,7 +28,7 @@ function string.ends_with(s, ends)
end
--- Tests if a string contains a given substring.
-- @tparam string s the string to check for the substring
-- @tparam string string s the to check for the substring
-- @tparam string contains the substring to test for
-- @treturn boolean true if the substring was found in the string
function string.contains(s, contains)
@@ -36,7 +36,7 @@ function string.contains(s, contains)
end
--- Tests whether a string is empty.
-- @tparam string s the string to test
-- @tparam string string s the to test
-- @treturn boolean true if the string is empty
function string.is_empty(s)
return s == nil or s == ''
@@ -45,9 +45,9 @@ end
--- Splits a string into an array.
-- *Note:* Empty split substrings are not included in the resulting table.
-- <p>For example, `string.split("foo.bar...", ".", false)` results in the table `{"foo", "bar"}`.
-- @tparam string s the string to split
-- @tparam string string s the to split
-- @tparam[opt="."] string sep the separator to use.
-- @tparam[opt=false] boolean pattern whether to interpret the separator as a lua pattern or plaintext for the string split
-- @tparam[opt=false] string boolean pattern whether to interpret the separator as a lua pattern or plaintext for the split
-- @treturn {string,...} an array of strings
function string.split(s, sep, pattern)
sep = sep or "."
@@ -76,7 +76,7 @@ end
--- Returns a string as a hex format (also a string)
-- @usage a = 'foo'
-- string.to_hex(a) -- return '666f6f'
-- @tparam string str the string to encode
-- @tparam string string str the to encode
-- @treturn string the hex format of the string
function string.to_hex(str)
if not is_type(str,'string') then return '' end

View File

@@ -11,8 +11,8 @@
---table.map(a, function(v) return v * 10 end) --produces: { 10, 20, 30, 40, 50 }
--- @usage a = {1, 2, 3, 4, 5}
---table.map(a, function(v, k, x) return v * k + x end, 100) --produces { 101, 104, 109, 116, 125}
-- @tparam table tbl the table to be mapped to the transform
-- @tparam function func the function to transform values
-- @tparam table table tbl the to be mapped to the transform
-- @tparam function function func the to transform values
-- @param[opt] ... additional arguments passed to the function
-- @treturn table a new table containing the keys and mapped values
function table.map(tbl, func, ...)
@@ -30,8 +30,8 @@ end
---table.filter(a, function(v) return v % 2 == 0 end) --produces: { 2, 4 }
--- @usage a = {1, 2, 3, 4, 5}
---table.filter(a, function(v, k, x) return k % 2 == 1 end) --produces: { 1, 3, 5 }
-- @tparam table tbl the table to be filtered
-- @tparam function func the function to filter values
-- @tparam table table tbl the to be filtered
-- @tparam function function func the to filter values
-- @param[opt] ... additional arguments passed to the function
-- @treturn table a new table containing the filtered key-value pairs
function table.filter(tbl, func, ...)
@@ -53,8 +53,8 @@ end
---table.find(a, function(v) return v % 2 == 0 end) --produces: 2
--- @usage a = {1, 2, 3, 4, 5}
---table.find(a, function(v, k, x) return k % 2 == 1 end) --produces: 1
-- @tparam table tbl the table to be searched
-- @tparam function func the function to use to search for any matching element
-- @tparam table table tbl the to be searched
-- @tparam function any func the function to use to search for matching element
-- @param[opt] ... additional arguments passed to the function
-- @treturn ?|nil|Mixed the first found value, or nil if none was found
function table.find(tbl, func, ...)
@@ -68,7 +68,7 @@ end
--- Finds the first index at which the value appears in the table
-- @usage table.index({'foo','bar','baz'},'bar') -- retuns 2,'bar'
-- @tparam table tbl the table to search though
-- @tparam table table tbl the to search though
-- @param value the value you want the index of
-- @treturn number the index that the value apeears at
-- @return the value in that possition
@@ -83,7 +83,7 @@ end
--- Returns a boolean on weather the table includes the value or not
-- @usage table.includes({'foo','bar','baz'},'bar') -- retuns true
-- @tparam table tbl the table to search though
-- @tparam table table tbl the to search though
-- @param value the value you want the index of
-- @treturn boolean if the table includes the value
function table.includes(tbl, value)
@@ -100,8 +100,8 @@ end
-- Passes the index as second argument to the function.
-- @usage a= { 1, 2, 3, 4, 5} table.any(a, function(v) return v % 2 == 0 end) --produces: true
-- @usage a = {1, 2, 3, 4, 5} table.any(a, function(v, k, x) return k % 2 == 1 end) --produces: true
-- @tparam table tbl the table to be searched
-- @tparam function func the function to use to search for any matching element
-- @tparam table table tbl the to be searched
-- @tparam function any func the function to use to search for matching element
-- @param[opt] ... additional arguments passed to the function
-- @treturn boolean true if an element was found, false if none was found
function table.any(tbl, func, ...)
@@ -114,8 +114,8 @@ end
-- @usage
-- a = {10, 20, 30, 40}
-- table.each(a, function(v) game.print(v) end) --prints 10, 20, 30, 40, 50
-- @tparam table tbl the table to be iterated
-- @tparam function func the function to apply to elements
-- @tparam table table tbl the to be iterated
-- @tparam function function func the to apply to elements
-- @param[opt] ... additional arguments passed to the function
-- @treturn table the table where the given function has been applied to its elements
function table.each(tbl, func, ...)
@@ -250,7 +250,7 @@ end
--- Creates a deep copy of table without copying Factorio objects.
-- @usage local copy = table.deepcopy[data.raw.["stone-furnace"]["stone-furnace"]] -- returns a copy of the stone furnace entity
-- @tparam table object the table to copy
-- @tparam table table object the to copy
-- @treturn table a copy of the table
function table.deepcopy(object)
local lookup_table = {}
@@ -294,7 +294,7 @@ local function sortFunc(x, y) --sorts tables with mixed index types.
end
--- Returns a copy of all of the values in the table.
-- @tparam table tbl the table to copy the keys from, or an empty table if tbl is nil
-- @tparam table table tbl the to copy the keys from, or an empty table if tbl is nil
-- @tparam[opt] boolean sorted whether to sort the keys (slower) or keep the random order from pairs()
-- @tparam[opt] boolean as_string whether to try and parse the values as strings, or leave them as their existing type
-- @treturn array an array with a copy of all the values in the table
@@ -320,7 +320,7 @@ function table.values(tbl, sorted, as_string)
end
--- Returns a copy of all of the keys in the table.
-- @tparam table tbl the table to copy the keys from, or an empty table if tbl is nil
-- @tparam table table tbl the to copy the keys from, or an empty table if tbl is nil
-- @tparam[opt] boolean sorted whether to sort the keys (slower) or keep the random order from pairs()
-- @tparam[opt] boolean as_string whether to try and parse the keys as strings, or leave them as their existing type
-- @treturn array an array with a copy of all the keys in the table
@@ -350,7 +350,7 @@ end
--table.remove_keys(a, {1,3}) --returns {nil, 2, nil, 4}
-- @usage local b = {k1 = 1, k2 = 'foo', old_key = 'bar'}
--table.remove_keys(b, {'old_key'}) --returns {k1 = 1, k2 = 'foo'}
-- @tparam table tbl the table to remove the keys from
-- @tparam table table tbl the to remove the keys from
-- @tparam {Mixed,...} keys an array of keys that exist in the given table
-- @treturn table tbl without the specified keys
function table.remove_keys(tbl, keys)
@@ -391,7 +391,7 @@ end
--table.invert(a) --returns {'foo' = k1, 'bar' = k2}
-- @usage local b = {k1 = 'foo', k2 = 'bar', k3 = 'bar'}
--table.invert(b) --returns {'foo' = k1, 'bar' = ?}
-- @tparam table tbl the table to invert
-- @tparam table table tbl the to invert
-- @treturn table a new table with inverted mapping
function table.invert(tbl)
local inverted = {}
@@ -410,7 +410,7 @@ table.size = table_size
--- For all string or number values in an array map them to a key = true table
-- @usage local a = {"v1", "v2"}
-- table.array_to_dict_bool(a) -- return {["v1"] = true, ["v2"]= true}
-- @tparam table tbl the table to convert
-- @tparam table table tbl the to convert
-- @treturn table the converted table
function table.arr_to_bool(tbl)
local newtbl = {}

View File

@@ -206,7 +206,7 @@ end
--- Acts as a bypass for running functions, can accept a string
-- @usage Server.interface('local x = 1+1 print(x) return x') -- return 2
-- @usage Server.interface('local x = 1+1 print(x)',true) -- will create a thread to run as root (this is the bypass)
-- @tparam ?string|function callback function to be ran
-- @tparam function ?string|function callback to be ran
-- @tparam[opt] ?Server._thread|true use_thread run the command on a pre-made thread or let it make its own
-- @tparam[opt] table env run the env to run the command in must have _env key as true to be
-- @param[opt] ... any args you want to pass to the function
@@ -467,8 +467,8 @@ end
--- Set function to run then an event is triggered, none of them are 'needed' but you are advised to have at least one
-- @usage thread:on_event('close',function) -- if event is not one below then a game event is used
-- @usage thread_only_events = ['close','timeout','tick','resolve','success','error']
-- @tparam ?string|index event the name of the event that the function should be called on
-- @tparam function callback the function which is called by the event trigger
-- @tparam function ?string|index event the name of the event that the should be called on
-- @tparam function function callback the which is called by the event trigger
-- @treturn table returns self so that they can be chained together
function Server._thread:on_event(event,callback)
local events = {'close','timeout','tick','resolve','success','error'}

View File

@@ -104,7 +104,7 @@ end
--- Logs an embed to the json.data we use a js script to add things we cant here
-- @usage Sync.emit_embedded{title='BAN',color='0x0',description='A player was banned' ... }
-- @tparam table args a table which contains everything that the embedded will use
-- @tparam table table args a which contains everything that the embedded will use
-- @see EmitEmbededParamaters
function Sync.emit_embedded(args)
if not is_type(args,'table') then error('Args table not given to Sync.emit_embedded',2) end
@@ -282,7 +282,7 @@ end
--- Adds a callback to be called when the info is updated
-- @usage Sync.add_update('players',function() return #game.players end)
-- @tparam string key the key that the value will be stored in
-- @tparam function callback the function which will return this value
-- @tparam function function callback the which will return this value
function Sync.add_update(key,callback)
if game then return end
if not is_type(callback,'function') then return end