update more comments

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")

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()

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

worldeditadditions_core/core/fetch_command_def.lua

@@ -1,3 +1,5 @@
+---
+-- @module worldeditadditions_core
 
 
 --- Fetches the definition of a WorldEditAdditions or WorldEdit command

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
 
 

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)
 	
 	---

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.")

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] = {

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.

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,

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 }.

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(),

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.

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)