Update and correct a bunch of comments

note that @module is outdated and should not be used

worldeditadditions/init.lua

@@ -1,7 +1,7 @@
 --- WorldEditAdditions
--- @module worldeditadditions
--- @release 0.1
--- @copyright 2018 Starbeamrainbowlabs
+-- @namespace worldeditadditions
+-- @release 1.13
+-- @copyright 2023 Starbeamrainbowlabs
 -- @license Mozilla Public License, 2.0
 -- @author Starbeamrainbowlabs
 

worldeditadditions/lib/bonemeal.lua

@@ -2,11 +2,12 @@ local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
 --- Bonemeal command.
--- Applies bonemeal to all notes 
--- @module worldeditadditions.overlay
-
--- strength		The strength to apply - see bonemeal:on_use
--- chance		Positive integer that represents the chance bonemealing will occur
+-- Applies bonemeal to all nodes with an air bloc above then.
+-- @param	strength	The strength to apply - see bonemeal:on_use
+-- @param	chance		Positive integer that represents the chance bonemealing will occur
+-- @returns	bool,number,number	1. Whether the command succeeded or not.
+-- 								2. The number of nodes actually bonemealed
+-- 								3. The number of possible candidates we could have bonemealed
 function worldeditadditions.bonemeal(pos1, pos2, strength, chance, nodename_list)
 	if not nodename_list then nodename_list = {} end
 	pos1, pos2 = Vector3.sort(pos1, pos2)

worldeditadditions/lib/copy.lua

@@ -1,8 +1,6 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
---- Copies a region to another location, potentially overwriting the exiting region.
--- @module worldeditadditions.copy
 
 --  ██████  ██████  ██████  ██    ██
 -- ██      ██    ██ ██   ██  ██  ██
@@ -10,6 +8,14 @@ local Vector3 = wea_c.Vector3
 -- ██      ██    ██ ██         ██
 --  ██████  ██████  ██         ██
 
+--- Copies a region to another location, potentially overwriting the exiting region.
+-- @param	source_pos1		Vector3		pos1 of the source region to copy.
+-- @param	source_pos2		Vector3		pos2 of the source region to copy.
+-- @param	target_pos1		Vector3		pos1 of the target region to copy to.
+-- @param	target_pos2		Vector3		pos2 of the target region to copy 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.
+-- @returns	bool,numbers	1. Whether the copy operation was successful or not
+-- 							2. The total number of nodes copied.
 function worldeditadditions.copy(source_pos1, source_pos2, target_pos1, target_pos2, airapply)
 	if airapply == nil then airapply = false end
 	source_pos1, source_pos2 = Vector3.sort(source_pos1, source_pos2)
@@ -27,7 +33,7 @@ function worldeditadditions.copy(source_pos1, source_pos2, target_pos1, target_p
 	local data_target = manip_target:get_data()
 	
 	-- 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_replaced = 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
@@ -42,6 +48,7 @@ function worldeditadditions.copy(source_pos1, source_pos2, target_pos1, target_p
 				end
 				if should_replace then
 					data_target[target_i] = data_source[source_i]
+					total_replaced = total_replaced + 1
 				end
 			end
 		end
@@ -50,5 +57,5 @@ function worldeditadditions.copy(source_pos1, source_pos2, target_pos1, target_p
 	-- Save the modified nodes back to disk & return
 	worldedit.manip_helpers.finish(manip_target, data_target)
 	
-	return true, worldedit.volume(target_pos1, target_pos2)
+	return true, total_replaced
 end

worldeditadditions/lib/count.lua

@@ -1,14 +1,19 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
---- Counts the nodes in a given area.
--- @module worldeditadditions.count
-
 --  ██████  ██████  ██    ██ ███    ██ ████████
 -- ██      ██    ██ ██    ██ ████   ██    ██
 -- ██      ██    ██ ██    ██ ██ ██  ██    ██
 -- ██      ██    ██ ██    ██ ██  ██ ██    ██
 --  ██████  ██████   ██████  ██   ████    ██
+
+--- Counts the nodes in a given area.
+-- @param	pos1			Vector3		pos1 of the defined region to count nodes in.
+-- @param	pos2			Vector3		pos2 of the defined region to count nodes in.
+-- @param	do_human_counts	bool		Whether to return human-readable counts (as a string) instead of the raw numbers.
+-- @returns	bool,table<number,number>,number	1. Whether the operation was successful or not.
+-- 												2. A table mapping node ids to the number of that node id seen.
+-- 												3. The total number of nodes counted.
 function worldeditadditions.count(pos1, pos2, do_human_counts)
 	pos1, pos2 = Vector3.sort(pos1, pos2)
 	-- pos2 will always have the highest co-ordinates now

worldeditadditions_commands/init.lua

@@ -1,5 +1,5 @@
 --- WorldEditAdditions-ChatCommands
--- @module worldeditadditions_commands
+-- @namespace worldeditadditions_commands
 -- @release 0.1
 -- @copyright 2018 Starbeamrainbowlabs
 -- @license Mozilla Public License, 2.0

worldeditadditions_core/init.lua

@@ -1,14 +1,10 @@
 --- WorldEditAdditions-Core
--- @module worldeditadditions_core
+-- @namespace worldeditadditions_core
 -- @release 1.13
 -- @copyright 2021 Starbeamrainbowlabs and VorTechnix
 -- @license Mozilla Public License, 2.0
 -- @author Starbeamrainbowlabs and VorTechnix
 
--- local temp = true
--- if temp then return end
--- This mod isn't finished yet, so it will not be executed for now.
-
 
 local modpath = minetest.get_modpath("worldeditadditions_core")
 

worldeditadditions_core/utils/vector3.lua

@@ -173,7 +173,7 @@ function Vector3.length(a)
 	return math.sqrt(a:length_squared())
 end
 
---- Calculates the volume of the region bounded by 1 points.
+--- Calculates the volume of the region bounded by 2 points.
 -- @param	a		Vector3		The first point bounding the target region.
 -- @param	b		Vector3		The second point bounding the target region.
 -- @returns	number	The volume of the defined region.