safe_region: update comment

We need @value

worldeditadditions/lib/floodfill.lua

@@ -3,9 +3,10 @@ local Vector3 = wea_c.Vector3
 
 
 --- Flood-fill command for complex lakes etc.
--- @module worldeditadditions.floodfill
-
-
+-- @param	start_pos		Vector3		The position to start floodfilling from.
+-- @param	radius			number		The maximum radius to limit the floodfill operation too.
+-- @param	replace_node	string		The (normalised) name of the node to replace with when floodfilling.
+-- @returns	number			The number of nodes replaced.
 function worldeditadditions.floodfill(start_pos, radius, replace_node)
 	start_pos = Vector3.clone(start_pos)
 	

worldeditadditions/lib/layers.lua

@@ -23,6 +23,7 @@ end
 -- @param	node_weights	string[]	
 -- @param	min_slope		number?		
 -- @param	max_slope		number?		
+-- @returns	table<string,number>
 function worldeditadditions.layers(pos1, pos2, node_weights, min_slope, max_slope)
 	pos1, pos2 = Vector3.sort(pos1, pos2)
 	if not min_slope then min_slope = math.rad(0) end

worldeditadditions/lib/line.lua

@@ -1,8 +1,6 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
---- Counts the nodes in a given area.
--- @module worldeditadditions.count
 
 -- ██      ██ ███    ██ ███████
 -- ██      ██ ████   ██ ██
@@ -10,7 +8,13 @@ local Vector3 = wea_c.Vector3
 -- ██      ██ ██  ██ ██ ██
 -- ███████ ██ ██   ████ ███████
 
-
+--- Counts the nodes in a given area.
+-- @param	pos1		Vector3		The position to start drawing the line from.
+-- @param	pos2		Vector3		The position to draw the line to.
+-- @param	thickness	number		The thickness of the line to draw.
+-- @param	node_name	string		The (normalised) name of the node to draw the line with.
+-- @returns	bool,{replaced=number}	1. A bool indicating whether the operation was successful or not.
+-- 									2. A table containing statistics. At present the only key in this table is `replaced`, which indicates the number of nodes replaced when drawing the line.
 function worldeditadditions.line(pos1, pos2, thickness, node_name)
 	local pos1_sorted, pos2_sorted = Vector3.sort(pos1, pos2)
 	-- pos2 will always have the highest co-ordinates now

worldeditadditions/lib/maze2d.lua

@@ -1,10 +1,6 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
---- Generates a maze.
--- Algorithm origin: https://starbeamrainbowlabs.com/blog/article.php?article=posts/070-Language-Review-Lua.html
--- @module worldeditadditions.maze
-
 
 ----------------------------------
 -- function to print out the world
@@ -119,6 +115,17 @@ end
 
 -- local world = maze(os.time(), width, height)
 
+--- Generates a 2D maze.
+-- **Algorithm origin:** https://starbeamrainbowlabs.com/blog/article.php?article=posts/070-Language-Review-Lua.html
+-- 
+-- The defined region must be at least 3 x 1 x 3 (x, y, z) for a maze to generate successfully.
+-- @param	pos1		Vector3		pos1 of the defined region to draw the 2D maze in in.
+-- @param	pos2		Vector3		pos2 of the defined region to draw the 2D maze in in.
+-- @param	target_node		string		The (normalised) node name to draw the maze in.
+-- @param	path_length=2	number		Step this many nodes forwards at once when generating the maze.  Higher values create long thin corridors.
+-- @param	path_width=1	number		Make all corridors this number of nodes wide when generating the maze. Higher values result in wider corridors.
+-- **Caution:** Make sure this value is not higher than `path_length - 1`, otherwise the maze algorithm won't work right!
+-- @returns	number			The number of nodes replaced (i.e. the volume fo the region defined by pos1 and pos2).
 function worldeditadditions.maze2d(pos1, pos2, target_node, seed, path_length, path_width)
 	pos1, pos2 = Vector3.sort(pos1, pos2)
 	-- pos2 will always have the highest co-ordinates now

worldeditadditions/lib/maze3d.lua

@@ -1,10 +1,6 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
---- Generates a maze.
--- Algorithm origin: https://starbeamrainbowlabs.com/blog/article.php?article=posts/070-Language-Review-Lua.html
--- @module worldeditadditions.maze
-
 ----------------------------------
 -- function to print out the world
 ----------------------------------
@@ -171,6 +167,20 @@ end
 
 -- local world = maze(os.time(), width, height)
 
+
+--- Generates a 3D maze.
+-- **Algorithm origin:** https://starbeamrainbowlabs.com/blog/article.php?article=posts/070-Language-Review-Lua.html
+-- 
+-- The defined region must be at least 3 x 3 x 3 (x, y, z) for a maze to generate.
+-- @param	pos1			Vector3		pos1 of the defined region to draw the 3D maze in in.
+-- @param	pos2			Vector3		pos2 of the defined region to draw the 3D maze in in.
+-- @param	target_node		string		The (normalised) node name to draw the maze in.
+-- @param	path_length=2	number		Step this many nodes forwards at once when generating the maze.  Higher values create long thin corridors.
+-- @param	path_width=1	number		Make all corridors this number of nodes wide when generating the maze. Higher values result in wider corridors.
+-- **Caution:** Make sure this value is not higher than `path_length - 1`, otherwise the maze algorithm won't work right!
+-- @param	path_depth=1	number		Make all corridors this number of nodes tall when generating the maze. Higher values results in higher ceilings in the maze.
+-- **Caution:** The same warning as with `path_width` applies here also!
+-- @returns	number			The number of nodes replaced (i.e. the volume fo the region defined by pos1 and pos2).
 function worldeditadditions.maze3d(pos1, pos2, target_node, seed, path_length, path_width, path_depth)
 	pos1, pos2 = Vector3.sort(pos1, pos2)
 	-- pos2 will always have the highest co-ordinates now

worldeditadditions/lib/move.lua

@@ -1,5 +1,3 @@
---- Copies a region to another location, potentially overwriting the exiting region.
--- @module worldeditadditions.copy
 
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
@@ -10,6 +8,15 @@ local Vector3 = wea_c.Vector3
 -- ██  ██  ██ ██    ██  ██  ██  ██
 -- ██      ██  ██████    ████   ███████
 
+--- Moves a region to another location, overwriting any nodes at the target location.
+-- @param	source_pos1		Vector3		pos1 of the source region to move.
+-- @param	source_pos2		Vector3		pos2 of the source region to move.
+-- @param	target_pos1		Vector3		pos1 of the target region to move to.
+-- @param	target_pos2		Vector3		pos2 of the target region to move to.
+-- @param	airapply=false	bool		Whether to only replace target nodes that are air-like, leaving those that are not air-like. If false, then all target nodes are replaced regardless of whether they are air-like nodes or not.
+-- **Caution:** If true, then **nodes in the source region will be removed and replaced with air, even if they are unable to be placed in the target location!**
+-- @returns	bool,numbers	1. Whether the move operation was successful or not
+-- 							2. The total number of nodes actually placed in the target region.
 function worldeditadditions.move(source_pos1, source_pos2, target_pos1, target_pos2, airapply)
 	---
 	-- 0: Preamble
@@ -38,6 +45,7 @@ function worldeditadditions.move(source_pos1, source_pos2, target_pos1, target_p
 	---
 	
 	-- z y x is the preferred loop order (because CPU cache, since then we're iterating linearly through the data array backwards. This only holds true for little-endian machines however)
+	local total_placed = 0
 	for z = source_pos2.z, source_pos1.z, -1 do
 		for y = source_pos2.y, source_pos1.y, -1 do
 			for x = source_pos2.x, source_pos1.x, -1 do
@@ -52,6 +60,7 @@ function worldeditadditions.move(source_pos1, source_pos2, target_pos1, target_p
 				end
 				if should_replace then
 					data_target[target_i] = data_source[source_i]
+					total_placed = total_placed + 1
 				end
 			end
 		end
@@ -96,7 +105,6 @@ function worldeditadditions.move(source_pos1, source_pos2, target_pos1, target_p
 				local source = Vector3.new(x, y, z)
 				local source_i = area_source:index(x, y, z)
 				local target = source:subtract(offset)
-				local target_i = area_target:index(target.x, target.y, target.z)
 				
 				if not source:is_contained(target_pos1, target_pos2) then
 					data_source[source_i] = node_id_air
@@ -118,5 +126,5 @@ function worldeditadditions.move(source_pos1, source_pos2, target_pos1, target_p
 	-- 6: Finish up and return
 	---
 	
-	return true, worldedit.volume(target_pos1, target_pos2)
+	return true, total_placed
 end

worldeditadditions/lib/noise/run2d.lua

@@ -2,19 +2,19 @@ local wea = worldeditadditions
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
---- Applies a layer of 2D noise over the terrain in the defined region.
--- @module worldeditadditions.noise2d
-
 
 -- ███    ██  ██████  ██ ███████ ███████ ██████  ██████
 -- ████   ██ ██    ██ ██ ██      ██           ██ ██   ██
 -- ██ ██  ██ ██    ██ ██ ███████ █████    █████  ██   ██
 -- ██  ██ ██ ██    ██ ██      ██ ██      ██      ██   ██
 -- ██   ████  ██████  ██ ███████ ███████ ███████ ██████
+
 --- Applies a layer of 2d noise over the terrain in the defined region.
 -- @param	pos1			Vector	pos1 of the defined region
 -- @param	pos2			Vector	pos2 of the defined region
 -- @param	noise_params	table	A noise parameters table.
+-- @returns	bool,table	1. Whether the operation was successful or not.
+-- 2. A table of statistics from the operation. See `worldeditadditions.noise.apply_2d` for the format of this table.
 function wea.noise.run2d(pos1, pos2, noise_params)
 	pos1, pos2 = Vector3.sort(pos1, pos2)
 	-- pos2 will always have the highest co-ordinates now

worldeditadditions/lib/overlay.lua

@@ -2,8 +2,16 @@ local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
 --- Overlap command. Places a specified node on top of each column.
--- @module worldeditadditions.overlay
-
+-- @param	pos1			Vector3		pos1 of the defined region to perform the overlay operation in.
+-- @param	pos2			Vector3		pos2 of the defined region to perform the overlay operation in.
+-- @param	node_weights	table<string,number>	A table mapping (normalised) node names to their relative weight. Nodes with a higher weight are placed more often than those with a lower weighting.
+-- Consider it like a ratio.
+-- @returns	table<string,number|table<number,number>>	A table of statistics about the operation performed.
+-- | Key		| Value Type	| Meaning		|
+-- |------------|---------------|---------------|
+-- | `updated`	| number		| The number of nodes placed. |
+-- | `skipped_columns` | number	| The number of columns skipped. This could be because there is no airlike not in that column, or the top node is not airlike. |
+-- | `placed`	| table<number,number> | A map of node ids to the number of that node that was placed. |
 function worldeditadditions.overlay(pos1, pos2, node_weights)
 	pos1, pos2 = Vector3.sort(pos1, pos2)
 	-- pos2 will always have the highest co-ordinates now

worldeditadditions/lib/replacemix.lua

@@ -1,9 +1,6 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
---- Like //mix, but replaces a given node instead.
--- @module worldeditadditions.replacemix
--- TODO: Implement //replacesplat, which picks seeder nodes with a percentage chance, and then some growth passes with e.g. cellular automata? We should probably be pushing towards a release though round about now
 
 -- ██████  ███████ ██████  ██       █████   ██████ ███████ ███    ███ ██ ██   ██
 -- ██   ██ ██      ██   ██ ██      ██   ██ ██      ██      ████  ████ ██  ██ ██
@@ -11,6 +8,17 @@ local Vector3 = wea_c.Vector3
 -- ██   ██ ██      ██      ██      ██   ██ ██      ██      ██  ██  ██ ██  ██ ██
 -- ██   ██ ███████ ██      ███████ ██   ██  ██████ ███████ ██      ██ ██ ██   ██
 
+--- Like //mix, but replaces a given node instead.
+-- TODO: Implement //replacesplat, which picks seeder nodes with a percentage chance, and then some growth passes with e.g. cellular automata? We should probably be pushing towards a release though round about now
+-- @param	pos1		Vector3		pos1 of the defined region to replace nodes in.
+-- @param	pos2		Vector3		pos2 of the defined region to replace nodes in.
+-- @param	target_node	string		The normalised name of the node to replace.
+-- @param	target_node_chance	number	The chance that the target_node should be replaced. This is a 1-in-N chance, so far example a value of 4 would be a 1 in 4 chance of replacement = 25% chance.
+-- @param	replacements		table<string,number>	A map of normalised node names to relative weights for the nodes to replace `target_node` with. Nodes with higher weights will be chosen to replace `target_node` more often.
+-- @returns	bool,number,number,table<number,number>		1. Whether the operation was successful or not.
+-- 2. The number of nodes actually placed.
+-- 3. The number of nodes that *could* have been replaced if `target_node_chance` were set to 1.
+-- 4. A map of node ids to the number of times that node was placed.
 function worldeditadditions.replacemix(pos1, pos2, target_node, target_node_chance, replacements)
 	pos1, pos2 = Vector3.sort(pos1, pos2)
 	-- pos2 will always have the highest co-ordinates now

worldeditadditions/lib/torus.lua

@@ -1,9 +1,6 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
---- Generates torus shapes.
--- @module worldeditadditions.torus
-
 --- Generates a torus shape at the given position with the given parameters.
 -- @param	position		Vector		The position at which to generate the torus.
 -- @param	major_radius	number		The major radius of the torus - i.e. the distance from the middle to the ring.
@@ -11,6 +8,7 @@ local Vector3 = wea_c.Vector3
 -- @param	target_node		string		The name of the target node to generate the torus with.
 -- @param	axes=xz			string|nil	The axes upon which the torus should lay flat.
 -- @param	hollow=false	boolean		Whether the generated torus should be hollow or not.
+-- @returns	number			The number of nodes replaced.
 function worldeditadditions.torus(position, major_radius, minor_radius, target_node, axes, hollow)
 	local matrix = {x='yz', y='xz', z='xy'}
 	if type(axes) ~= "string" then axes = "xz" end

worldeditadditions_commands/commands/meta/many.lua

@@ -1,5 +1,4 @@
---- Executes multiple worldedit commands in sequence.
--- @module worldeditadditions_commands.multi
+-- Executes multiple worldedit commands in sequence.
 
 local wea_c = worldeditadditions_core
 

worldeditadditions_commands/commands/meta/multi.lua

@@ -1,5 +1,5 @@
---- Executes multiple worldedit commands in sequence.
--- @module worldeditadditions_commands.multi
+-- Executes multiple worldedit commands in sequence.
+-- **Warning:** If a command is asynchronous (i.e. it doesn't finish when the function registered in the chat command returns), the next command will be executed before the previous one is finished! The solution to this is an implementation of Promise<any> and then ensuring that all functions registered are thenable as in JS, but this has not been implemented yet.
 local wea_c = worldeditadditions_core
 
 minetest.register_chatcommand("/multi", {

worldeditadditions_core/core/safe_region.lua

@@ -13,6 +13,8 @@ if minetest.global_exists("worldedit") then
 end
 
 --- A table that holds at most 1 pending function call per player.
+-- @value	table<string,function>
+-- @internal
 local pending_calls = {}
 
 --- Captures the given function in the safe_region subsystem for later execution.