Ldoc compliant

expcore/roles.lua

@@ -246,8 +246,8 @@ function Roles.debug()
 end
 
 --- Prints a message to all players in the given roles, may send duplicate message however factorio blocks spam
--- @tparam roles table a table of roles which to send the message to
--- @tparam message string the message to send to the players
+-- @tparam table roles table a of roles which to send the message to
+-- @tparam string message the message to send to the players
 function Roles.print_to_roles(roles,message)
     for _,role in pairs(roles) do
         role = Roles.get_role_from_any(role)
@@ -256,8 +256,8 @@ function Roles.print_to_roles(roles,message)
 end
 
 --- Prints a message to all players who have the given role or one which is higher (excluding default)
--- @tparam role string the name of the role to send the message to
--- @tparam message string the message to send to the players
+-- @tparam string role the name of the role to send the message to
+-- @tparam string message the message to send to the players
 function Roles.print_to_roles_higher(role,message)
     role = Roles.get_role_from_any(role)
     if not role then return end
@@ -271,8 +271,8 @@ function Roles.print_to_roles_higher(role,message)
 end
 
 --- Prints a message to all players who have the given role or one which is lower (excluding default)
--- @tparam role string the name of the role to send the message to
--- @tparam message string the message to send to the players
+-- @tparam string role the name of the role to send the message to
+-- @tparam string message the message to send to the players
 function Roles.print_to_roles_lower(role,message)
     role = Roles.get_role_from_any(role)
     if not role then return end
@@ -286,14 +286,14 @@ function Roles.print_to_roles_lower(role,message)
 end
 
 --- Get a role for the given name
--- @tparam name string the name of the role to get
+-- @tparam string name the name of the role to get
 -- @treturn Roles._prototype the role with that name or nil
 function Roles.get_role_by_name(name)
     return Roles.config.roles[name]
 end
 
 --- Get a role with the given order index
--- @tparam index number the place in the oder list of the role to get
+-- @tparam number index the place in the oder list of the role to get
 -- @treturn Roles._prototype the role with that index in the order list or nil
 function Roles.get_role_by_order(index)
     local name = Roles.config.order[index]
@@ -302,7 +302,7 @@ end
 
 --- Gets a role from a name,index or role object (where it is just returned)
 -- nb: this function is used for the input for most outward facing functions
--- @tparam any ?number|string|table the value used to find the role
+-- @tparam ?number|string|table any the value used to find the role
 -- @treturn Roles._prototype the role that was found or nil see above
 function Roles.get_role_from_any(any)
     local tany = type(any)
@@ -317,7 +317,7 @@ function Roles.get_role_from_any(any)
 end
 
 --- Gets all the roles of the given player, this will always contain the default role
--- @tparam player LuaPlayer the player to get the roles of
+-- @tparam LuaPlayer player the player to get the roles of
 -- @treturn table a table where the values are the roles which the player has
 function Roles.get_player_roles(player)
     player = Game.get_player_from_any(player)
@@ -332,7 +332,7 @@ function Roles.get_player_roles(player)
 end
 
 --- Gets the highest role which the player has, can be used to compeer one player to another
--- @tparam player LuaPlayer the player to get the highest role of
+-- @tparam LuaPlayer player the player to get the highest role of
 -- @treturn the role with the highest order index which this player has
 function Roles.get_player_highest_role(player)
     local roles = Roles.get_player_roles(player)
@@ -347,10 +347,10 @@ function Roles.get_player_highest_role(player)
 end
 
 --- Gives a player the given role(s) with an option to pass a by player name used in the log
--- @tparam player LuaPlayer the player that will be assigned the roles
--- @tparam role table a table of roles that the player will be given, can be one role and can be role names
--- @tparam[opt=<server>] by_player_name string the name of the player that will be shown in the log
--- @tparam[opt=false] silent boolean when true there will be no game message printed
+-- @tparam LuaPlayer player the player that will be assigned the roles
+-- @tparam table roles table a of roles that the player will be given, can be one role and can be role names
+-- @tparam[opt=<server>] string by_player_name the name of the player that will be shown in the log
+-- @tparam[opt=false] boolean silent when true there will be no game message printed
 function Roles.assign_player(player,roles,by_player_name,silent)
     player = Game.get_player_from_any(player)
     if not player then return end
@@ -367,10 +367,10 @@ function Roles.assign_player(player,roles,by_player_name,silent)
 end
 
 --- Removes a player from the given role(s) with an option to pass a by player name used in the log
--- @tparam player LuaPlayer the player that will have the roles removed
--- @tparam roles table a table of roles to be removed from the player, can be one role and can be role names
--- @tparam[opt=<server>] by_player_name string the name of the player that will be shown in the logs
--- @tparam[opt=false] silent boolean when true there will be no game message printed
+-- @tparam LuaPlayer player the player that will have the roles removed
+-- @tparam table roles table a of roles to be removed from the player, can be one role and can be role names
+-- @tparam[opt=<server>] string by_player_name the name of the player that will be shown in the logs
+-- @tparam[opt=false] boolean silent when true there will be no game message printed
 function Roles.unassign_player(player,roles,by_player_name,silent)
     player = Game.get_player_from_any(player)
     if not player then return end
@@ -387,14 +387,14 @@ function Roles.unassign_player(player,roles,by_player_name,silent)
 end
 
 --- Overrides all player roles with the given table of roles, useful to mass set roles on game start
--- @tparam roles table a table which is indexed by case sensitive player names and has the value of a table of role names
+-- @tparam table roles table a which is indexed by case sensitive player names and has the value of a table of role names
 function Roles.override_player_roles(roles)
     Roles.config.players = roles
 end
 
 --- A test for weather a player has the given role
--- @tparam player LuaPlayer the player to test the roles of
--- @tparam search_role ?string|number|table a pointer to the role that is being searched for
+-- @tparam LuaPlayer player the player to test the roles of
+-- @tparam ?string|number|table search_role a pointer to the role that is being searched for
 -- @treturn boolean true if the player has the role, false otherwise, nil for errors
 function Roles.player_has_role(player,search_role)
     local roles = Roles.get_player_roles(player)
@@ -408,8 +408,8 @@ function Roles.player_has_role(player,search_role)
 end
 
 --- A test for weather a player has the given flag true for at least one of they roles
--- @tparam player LuaPlayer the player to test the roles of
--- @tparam flag_name string the name of the flag that is being looked for
+-- @tparam LuaPlayer player the player to test the roles of
+-- @tparam string flag_name the name of the flag that is being looked for
 -- @treturn boolean true if the player has at least one role which has the flag set to true, false otherwise, nil for errors
 function Roles.player_has_flag(player,flag_name)
     local roles = Roles.get_player_roles(player)
@@ -423,8 +423,8 @@ function Roles.player_has_flag(player,flag_name)
 end
 
 --- A test for weather a player has at least one role which is allowed the given action
--- @tparam player LuaPlayer the player to test the roles of
--- @tparam action string the name of the action that is being tested for
+-- @tparam LuaPlayer player the player to test the roles of
+-- @tparam string action the name of the action that is being tested for
 -- @treturn boolean true if the player has at least one role which is allowed this action, false otherwise, nil for errors
 function Roles.player_allowed(player,action)
     local roles = Roles.get_player_roles(player)
@@ -439,7 +439,7 @@ end
 
 --- Used to set the role order, higher in the list is better, must be called at least once in config
 -- nb: function also re links parents due to expected position in the config file
--- @tparam order table a table which is keyed only by numbers (start 1) and values are roles in order with highest first
+-- @tparam table order table a which is keyed only by numbers (start 1) and values are roles in order with highest first
 function Roles.define_role_order(order)
     -- Clears and then rebuilds the order table
     Roles.config.order = {}
@@ -462,8 +462,8 @@ function Roles.define_role_order(order)
 end
 
 --- Defines a new trigger for when a tag is added or removed from a player
--- @tparam name string the name of the flag which the roles will have
--- @tparam callback function the function that is called when roles are assigned
+-- @tparam string name the name of the flag which the roles will have
+-- @tparam function callback the function that is called when roles are assigned
 -- flag param - player - the player that has had they roles changed
 -- flag param - state - the state of the flag, aka if the flag is present
 function Roles.define_flag_trigger(name,callback)
@@ -471,7 +471,7 @@ function Roles.define_flag_trigger(name,callback)
 end
 
 --- Sets the default role which every player will have, this needs to be called at least once
--- @tparam name string the name of the default role
+-- @tparam string name the name of the default role
 function Roles.set_default(name)
     local role = Roles.config.roles[name]
     if not role then return end
@@ -479,7 +479,7 @@ function Roles.set_default(name)
 end
 
 --- Sets the root role which will always have all permissions, any server actions act from this role
--- @tparam name string the name of the root role
+-- @tparam string name the name of the root role
 function Roles.set_root(name)
     local role = Roles.config.roles[name]
     if not role then return end
@@ -488,8 +488,8 @@ function Roles.set_root(name)
 end
 
 --- Defines a new role and returns the prototype to allow configuration
--- @tparam name string the name of the new role, must be unique
--- @tparam[opt=name] shirt_hand string the shortened version of the name
+-- @tparam string name the name of the new role, must be unique
+-- @tparam[opt=name] string short_hand the shortened version of the name
 -- @treturn Roles._prototype the start of the config chain for this role
 function Roles.new_role(name,short_hand)
     if Roles.config.roles[name] then return error('Role name is non unique') end
@@ -505,7 +505,7 @@ function Roles.new_role(name,short_hand)
 end
 
 --- Sets the default allow state of the role, true will allow all actions
--- @tparam[opt=true] strate boolean true will allow all actions
+-- @tparam[opt=true] boolean state true will allow all actions
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:set_allow_all(state)
     if state == nil then state = true end
@@ -514,7 +514,7 @@ function Roles._prototype:set_allow_all(state)
 end
 
 --- Sets the allow actions for this role, actions in this list will be allowed for this role
--- @tparam actions table indexed with numbers and is an array of action names, order has no effect
+-- @tparam table actions indexed with numbers and is an array of action names, order has no effect
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:allow(actions)
     if type(actions) ~= 'table' then
@@ -527,7 +527,7 @@ function Roles._prototype:allow(actions)
 end
 
 --- Sets the disallow actions for this role, will prevent actions from being allowed regardless of inheritance
--- @tparam actions table indexed with numbers and is an array of action names, order has no effect
+-- @tparam table actions indexed with numbers and is an array of action names, order has no effect
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:disallow(actions)
     if type(actions) ~= 'table' then
@@ -540,7 +540,7 @@ function Roles._prototype:disallow(actions)
 end
 
 --- Test for if a role is allowed the given action, mostly internal see Roles.player_allowed
--- @tparam action string the name of the action to test if it is allowed
+-- @tparam string action the name of the action to test if it is allowed
 -- @treturn boolean true if action is allowed, false otherwise
 function Roles._prototype:is_allowed(action)
     local is_root = Roles.config.internal.root.name == self.name
@@ -548,8 +548,8 @@ function Roles._prototype:is_allowed(action)
 end
 
 --- Sets the state of a flag for a role, flags can be used to apply effects to players
--- @tparam name string the name of the flag to set the value of
--- @tparam[opt=true] value boolean the state to set the flag to
+-- @tparam string name the name of the flag to set the value of
+-- @tparam[opt=true] boolean value the state to set the flag to
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:set_flag(name,value)
     if value == nil then value = true end
@@ -565,14 +565,14 @@ function Roles._prototype:clear_flags()
 end
 
 --- A test for if the role has a flag set
--- @tparam name string the name of the flag to test for
+-- @tparam string name the name of the flag to test for
 -- @treturn boolean true if the flag is set, false otherwise
 function Roles._prototype:has_flag(name)
     return self.flags[name] or false
 end
 
 --- Sets a custom player tag for the role, can be accessed by other code
--- @tparam tag string the value that the tag will be
+-- @tparam string tag the value that the tag will be
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:set_custom_tag(tag)
     self.custom_tag = tag
@@ -580,7 +580,7 @@ function Roles._prototype:set_custom_tag(tag)
 end
 
 --- Sets a custom colour for the role, can be accessed by other code
--- @tparam color ?string|table can either be and rgb colour table or the name of a colour defined in the presets
+-- @tparam table color ?string|table can either be and rgb colour or the name of a colour defined in the presets
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:set_custom_color(color)
     if type(color) ~= 'table' then
@@ -591,8 +591,8 @@ function Roles._prototype:set_custom_color(color)
 end
 
 --- Sets the permission group for this role, players will be moved to the group of they highest role
--- @tparam name string the name of the permission group to have players moved to
--- @tparam[opt=false] use_factorio_api boolean when true the custom permission group module is ignored
+-- @tparam string name the name of the permission group to have players moved to
+-- @tparam[opt=false] boolean use_factorio_api when true the custom permission group module is ignored
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:set_permission_group(name,use_factorio_api)
     if use_factorio_api then
@@ -607,7 +607,7 @@ end
 
 --- Sets the parent for a role, any action not in allow or disallow will be looked for in its parents
 -- nb: this is a recursive action, and changing the allows and disallows will effect all children roles
--- @tparam role string the name of the role that will be the parent; has imminent effect if role is already defined
+-- @tparam string role the name of the role that will be the parent; has imminent effect if role is already defined
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:set_parent(role)
     self.parent = role
@@ -619,7 +619,7 @@ end
 
 --- Sets an auto promote condition that is checked every 5 seconds, if true is returned then the player will recive the role
 -- nb: this is one way, failing false after already gaining the role will not revoke the role
--- @tparam callback function receives only one param which is player to promote, return true to promote the player
+-- @tparam function callback receives only one param which is player to promote, return true to promote the player
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:set_auto_promote_condition(callback)
     self.auto_promote_condition = callback
@@ -627,7 +627,7 @@ function Roles._prototype:set_auto_promote_condition(callback)
 end
 
 --- Sets the role to not allow players to have auto promote effect them, useful to keep people locked to a punishment
--- @tparam[opt=true] state boolean when true the players with this role will not be auto promoted
+-- @tparam[opt=true] boolean state when true the players with this role will not be auto promoted
 -- @treturn Roles._prototype allows chaining
 function Roles._prototype:set_block_auto_promote(state)
     if state == nil then state = true end
@@ -636,9 +636,9 @@ function Roles._prototype:set_block_auto_promote(state)
 end
 
 --- Adds a player to this role, players can have more than one role at a time, used internally see Roles.assign
--- @tparam player LuaPlayer the player that will be given this role
--- @tparam skip_check boolean when true player will be taken as the player name (use when player has not yet joined)
--- @tparam skip_event boolean when true the event emit will be skipped, this is used internally with Roles.assign
+-- @tparam LuaPlayer player the player that will be given this role
+-- @tparam boolean skip_check when true player will be taken as the player name (use when player has not yet joined)
+-- @tparam boolean skip_event when true the event emit will be skipped, this is used internally with Roles.assign
 -- @treturn boolean true if the player was added successfully
 function Roles._prototype:add_player(player,skip_check,skip_event)
     player = Game.get_player_from_any(player)
@@ -670,9 +670,9 @@ function Roles._prototype:add_player(player,skip_check,skip_event)
 end
 
 --- Removes a player from this role, players can have more than one role at a time, used internally see Roles.unassign
--- @tparam player LuaPlayer the player that will lose this role
--- @tparam skip_check boolean when true player will be taken as the player name (use when player has not yet joined)
--- @tparam skip_event boolean when true the event emit will be skipped, this is used internally with Roles.unassign
+-- @tparam LuaPlayer player the player that will lose this role
+-- @tparam boolean skip_check when true player will be taken as the player name (use when player has not yet joined)
+-- @tparam boolean skip_event when true the event emit will be skipped, this is used internally with Roles.unassign
 -- @treturn boolean true if the player was removed successfully
 function Roles._prototype:remove_player(player,skip_check,skip_event)
     player = Game.get_player_from_any(player)
@@ -709,7 +709,7 @@ function Roles._prototype:remove_player(player,skip_check,skip_event)
 end
 
 --- Returns an array of all the players who have this role, can be filtered by online status
--- @tparam[opt=nil] online boolean when given will filter by this online state, nil will return all players
+-- @tparam[opt=nil] boolean online when given will filter by this online state, nil will return all players
 -- @treturn table all the players who have this role, indexed order is meaningless
 function Roles._prototype:get_players(online)
     local players = {}
@@ -740,7 +740,7 @@ function Roles._prototype:get_players(online)
 end
 
 --- Will print a message to all players with this role
--- @tparam message string the message that will be printed to the players
+-- @tparam string message the message that will be printed to the players
 -- @treturn number the number of players who received the message
 function Roles._prototype:print(message)
     local players = self:get_players(true)