From 76c02cd42f2fb676eba9d5c90af8a6402824e36b Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Thu, 3 Aug 2023 14:37:05 +0100 Subject: [PATCH] update more comments --- worldeditadditions_core/core/entities/init.lua | 5 ++--- worldeditadditions_core/core/entities/pos_marker.lua | 3 ++- .../core/entities/pos_marker_wall.lua | 2 ++ worldeditadditions_core/core/fetch_command_def.lua | 2 ++ worldeditadditions_core/core/register_alias.lua | 10 ++++++++++ worldeditadditions_core/core/register_command.lua | 4 +++- worldeditadditions_core/core/run_command.lua | 8 ++++++++ worldeditadditions_core/core/safe_region.lua | 6 +++++- worldeditadditions_core/utils/parse/chance.lua | 4 ++++ worldeditadditions_core/utils/parse/init.lua | 2 ++ worldeditadditions_core/utils/parse/map.lua | 3 +++ worldeditadditions_core/utils/parse/seed.lua | 3 +++ .../utils/parse/tokenise_commands.lua | 4 +++- worldeditadditions_core/utils/parse/weighted_nodes.lua | 5 +++++ 14 files changed, 54 insertions(+), 7 deletions(-) diff --git a/worldeditadditions_core/core/entities/init.lua b/worldeditadditions_core/core/entities/init.lua index 6068dba..9521c12 100644 --- a/worldeditadditions_core/core/entities/init.lua +++ b/worldeditadditions_core/core/entities/init.lua @@ -4,11 +4,10 @@ -- ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ -- ███████ ██ ████ ██ ██ ██ ██ ███████ ███████ ---- Entities and functions to manage them. --- @namespace worldeditadditions_core.entities - local wea_c = worldeditadditions_core +--- Entities and functions to manage them. +-- @namespace worldeditadditions_core.entities return { pos_marker = dofile(wea_c.modpath.."/core/entities/pos_marker.lua"), pos_marker_wall = dofile(wea_c.modpath.."/core/entities/pos_marker_wall.lua") diff --git a/worldeditadditions_core/core/entities/pos_marker.lua b/worldeditadditions_core/core/entities/pos_marker.lua index dff3c7d..a63483c 100644 --- a/worldeditadditions_core/core/entities/pos_marker.lua +++ b/worldeditadditions_core/core/entities/pos_marker.lua @@ -1,7 +1,8 @@ local wea_c = worldeditadditions_core local EventEmitter = worldeditadditions_core.EventEmitter - +--- +-- @module worldeditadditions_core.entities.pos_marker_wall local anchor local function make_id() diff --git a/worldeditadditions_core/core/entities/pos_marker_wall.lua b/worldeditadditions_core/core/entities/pos_marker_wall.lua index 81d50d4..2691184 100644 --- a/worldeditadditions_core/core/entities/pos_marker_wall.lua +++ b/worldeditadditions_core/core/entities/pos_marker_wall.lua @@ -2,6 +2,8 @@ local wea_c = worldeditadditions_core local EventEmitter = worldeditadditions_core.EventEmitter local Vector3 = wea_c.Vector3 +--- +-- @module worldeditadditions_core.entities.pos_marker_wall local anchor local entity_wall_size = 10 diff --git a/worldeditadditions_core/core/fetch_command_def.lua b/worldeditadditions_core/core/fetch_command_def.lua index 956e733..a8fd146 100644 --- a/worldeditadditions_core/core/fetch_command_def.lua +++ b/worldeditadditions_core/core/fetch_command_def.lua @@ -1,3 +1,5 @@ +--- +-- @module worldeditadditions_core --- Fetches the definition of a WorldEditAdditions or WorldEdit command diff --git a/worldeditadditions_core/core/register_alias.lua b/worldeditadditions_core/core/register_alias.lua index 011b70c..534f56b 100644 --- a/worldeditadditions_core/core/register_alias.lua +++ b/worldeditadditions_core/core/register_alias.lua @@ -1,6 +1,14 @@ local wea_c = worldeditadditions_core +--- +-- @module worldeditadditions_core + +--- Register an alias of an existing worldeditadditions/worldedit command. +-- @param cmdname_target string The target name for the alias +-- @param cmdname_source string The source name of the command to alias the target to. +-- @param override=false bool Whether to override the target command name if it exists. Defaults to false, which results in an error being thrown if the target command name already exists. +-- @returns bool Whether the override operation was successful or not. local function register_alias(cmdname_target, cmdname_source, override) if override == nil then override = false end @@ -34,6 +42,8 @@ local function register_alias(cmdname_target, cmdname_source, override) if minetest.global_exists("worldedit") then worldedit.registered_commands[cmdname_target] = worldedit.registered_commands[cmdname_source] end + + return true end diff --git a/worldeditadditions_core/core/register_command.lua b/worldeditadditions_core/core/register_command.lua index 87e5960..e6a829b 100644 --- a/worldeditadditions_core/core/register_command.lua +++ b/worldeditadditions_core/core/register_command.lua @@ -4,7 +4,8 @@ -- ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ -- ██ ██ ███████ ██████ ██ ███████ ██ ███████ ██ ██ --- WorldEditAdditions chat command registration +--- WorldEditAdditions chat command registration +-- @module worldeditadditions_core local wea_c = worldeditadditions_core local run_command = dofile(wea_c.modpath.."/core/run_command.lua") @@ -12,6 +13,7 @@ local function log_error(cmdname, error_message) minetest.log("error", "register_command("..cmdname..") error: "..error_message) end +--- TODO: Document this function local function register_command(cmdname, options) --- diff --git a/worldeditadditions_core/core/run_command.lua b/worldeditadditions_core/core/run_command.lua index 25d4450..6b4dff4 100644 --- a/worldeditadditions_core/core/run_command.lua +++ b/worldeditadditions_core/core/run_command.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core + -- WARNING: safe_region MUST NOT be imported more than once, as it defines chat commands. If you want to import it again elsewhere, check first that multiple dofile() calls don't execute a file more than once. local wea_c = worldeditadditions_core local safe_region = dofile(wea_c.modpath.."/core/safe_region.lua") @@ -13,6 +16,11 @@ local function run_command_stage2(player_name, func, parse_result) end end +--- Runs a command with the given name and options for the given player. +-- @param cmdname string The name of the command to run. +-- @param options table The table of options associated with the command. See worldeditadditions_core.register_command for more information. +-- @param player_name string The name of the player to execute the command for. +-- @param paramtext string The unparsed argument string to pass to the command when executing it. local function run_command(cmdname, options, player_name, paramtext) if options.require_pos > 0 and not worldedit.pos1[player_name] and not wea_c.pos.get1(player_name) then worldedit.player_notify(player_name, "Error: pos1 must be selected to use this command.") diff --git a/worldeditadditions_core/core/safe_region.lua b/worldeditadditions_core/core/safe_region.lua index ea821a4..e85b011 100644 --- a/worldeditadditions_core/core/safe_region.lua +++ b/worldeditadditions_core/core/safe_region.lua @@ -5,6 +5,8 @@ -- ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ -- ███████ ██ ██ ██ ███████ ██ ██ ███████ ██████ ██ ██████ ██ ████ +--- +-- @module worldeditadditions_core local worldedit_command_y, worldedit_command_n if minetest.global_exists("worldedit") then @@ -18,9 +20,11 @@ end local pending_calls = {} --- Captures the given function in the safe_region subsystem for later execution. +-- CAUTION: This command is not available for general use. +-- @internal -- @param player_name string The name of the player. -- @param cmdname string The name of the command being executed. --- @param func function The function to execute later. Will be passed NO ARGUMENTS should it ever get executed in the future (this is not guaranteed). +-- @param func function The function to execute later. Will be passed NO ARGUMENTS should it ever get executed in the future (though its future execution is not guaranteed). -- @returns nil local function safe_region(player_name, cmdname, func) pending_calls[player_name] = { diff --git a/worldeditadditions_core/utils/parse/chance.lua b/worldeditadditions_core/utils/parse/chance.lua index 81ce14f..3ebd2cc 100644 --- a/worldeditadditions_core/utils/parse/chance.lua +++ b/worldeditadditions_core/utils/parse/chance.lua @@ -1,3 +1,7 @@ +--- +-- @module worldeditadditions_core.parse + + --- Parses a chance value, and returns the 1-in-N value thereof. -- @param str string The string to parse. diff --git a/worldeditadditions_core/utils/parse/init.lua b/worldeditadditions_core/utils/parse/init.lua index 19dc236..b33b79d 100644 --- a/worldeditadditions_core/utils/parse/init.lua +++ b/worldeditadditions_core/utils/parse/init.lua @@ -11,6 +11,8 @@ local uak_parse = dofile(wea_c.modpath.."/utils/parse/axes_parser.lua") -- Old axis parsing functions local axes = dofile(wea_c.modpath.."/utils/parse/axes.lua") +--- Functions for parsing things. +-- @namespace worldeditadditions_core.parse wea_c.parse = { direction_keyword = uak_parse.keyword, directions = uak_parse.keytable, diff --git a/worldeditadditions_core/utils/parse/map.lua b/worldeditadditions_core/utils/parse/map.lua index 1446f64..555ae9d 100644 --- a/worldeditadditions_core/utils/parse/map.lua +++ b/worldeditadditions_core/utils/parse/map.lua @@ -1,6 +1,9 @@ ---@diagnostic disable: cast-local-type local wea_c = worldeditadditions_core +--- +-- @module worldeditadditions_core.parse + --- Parses a map of key-value pairs into a table. -- For example, "count 25000 speed 0.8 rate_erosion 0.006 doawesome true" would be parsed into -- the following table: { count = 25000, speed = 0.8, rate_erosion = 0.006, doawesome = true }. diff --git a/worldeditadditions_core/utils/parse/seed.lua b/worldeditadditions_core/utils/parse/seed.lua index 3692d95..a3c78cd 100644 --- a/worldeditadditions_core/utils/parse/seed.lua +++ b/worldeditadditions_core/utils/parse/seed.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.parse + --- Makes a seed from a string. -- If the input is a number, it is returned as-is. -- If the input is a string and can be converted to a number with tonumber(), diff --git a/worldeditadditions_core/utils/parse/tokenise_commands.lua b/worldeditadditions_core/utils/parse/tokenise_commands.lua index 8209a7a..0fc6a61 100644 --- a/worldeditadditions_core/utils/parse/tokenise_commands.lua +++ b/worldeditadditions_core/utils/parse/tokenise_commands.lua @@ -1,9 +1,11 @@ local wea_c = worldeditadditions_core ---- Uncomment these 2 lines to run in standalone mode +--= Uncomment these 2 lines to run in standalone mode -- worldeditadditions = { parse = { } } -- function wea_c.trim(str) return (str:gsub("^%s*(.-)%s*$", "%1")) end +--- +-- @module worldeditadditions_core.parse --- The main tokeniser. Splits the input string up into space separated tokens, except when said spaces are inside { curly braces }. -- Note that the outermost set of curly braces are stripped. diff --git a/worldeditadditions_core/utils/parse/weighted_nodes.lua b/worldeditadditions_core/utils/parse/weighted_nodes.lua index 3489886..602233a 100644 --- a/worldeditadditions_core/utils/parse/weighted_nodes.lua +++ b/worldeditadditions_core/utils/parse/weighted_nodes.lua @@ -1,4 +1,9 @@ local wea_c = worldeditadditions_core + +--- +-- @module worldeditadditions_core.parse + + --- Parses a list of strings as a list of weighted nodes - e.g. like in -- the //mix command. Example: "dirt 5 stone sand 2". -- @param parts string[] The list of strings to parse (try worldeditadditions_core.split)