comments: update

worldeditadditions_core/utils/bit.lua

@@ -4,14 +4,19 @@
 -- ██   ██ ██    ██
 -- ██████  ██    ██
 
--- LuaJIT bit polyfill
--- @source https://github.com/Rabios/polyfill.lua/blob/master/polyfill.lua
--- Adapted for Minetest by Starbeamrainbowlabs
--- Note that this file is MIT licenced, and NOT MPL-2.0!
--- @licence MIT
--- Docs: http://bitop.luajit.org/api.html
 
--- module: bit
+--- LuaJIT bit polyfill
+-- Adapted for Minetest by Starbeamrainbowlabs
+-- 
+-- Note that this file is MIT licenced, and NOT MPL-2.0!
+-- 
+-- Docs: http://bitop.luajit.org/api.html
+-- 
+-- TODO: Document these.
+-- @module worldeditadditions_core.bit
+-- @source https://github.com/Rabios/polyfill.lua/blob/master/polyfill.lua
+-- @licence MIT
+
 
 local bit_local
 

worldeditadditions_core/utils/chaikin.lua

@@ -1,6 +1,12 @@
 local wea_c = worldeditadditions_core
 
+--- 
+-- @module worldeditadditions_core
+
+
 --- Interpolates between the 2 given points
+-- 
+-- TODO: refactor numbers.lua and move this function into there instead
 -- @param	a		Vector3|number		The starting point.
 -- @param	b		Vector3|number		The ending point.
 -- @param	time	number				The percentage between 0 and 1 to interpolate to.

worldeditadditions_core/utils/inspect.lua

@@ -1,3 +1,12 @@
+-- ██ ███    ██ ███████ ██████  ███████  ██████ ████████ 
+-- ██ ████   ██ ██      ██   ██ ██      ██         ██    
+-- ██ ██ ██  ██ ███████ ██████  █████   ██         ██    
+-- ██ ██  ██ ██      ██ ██      ██      ██         ██    
+-- ██ ██   ████ ███████ ██      ███████  ██████    ██    
+
+---
+-- @module worldeditadditions_core
+
 --- Serialises an arbitrary value to a string.
 -- Note that although the resulting table *looks* like valid Lua, it isn't.
 -- Completely arbitrarily, if a table (or it's associated metatable) has the

worldeditadditions_core/utils/io.lua

@@ -1,3 +1,7 @@
+
+--- Functions to abstract file I/O away.
+-- I'm very suspicious of Minetest's API changing from under our feet.
+-- @namespace worldeditadditions_core.io
 local io = {
 	-- Ref https://minetest.gitlab.io/minetest/minetest-namespace-reference/#utilities
 	scandir = function(dirpath)

worldeditadditions_core/utils/lru_benchmark.lua

@@ -21,7 +21,7 @@ local function round(num, numDecimalPlaces)
 	return math.floor(num * mult + 0.5) / mult
 end
 
---- Pads str to length len with char from right
+-- Pads str to length len with char from right
 -- @source https://snipplr.com/view/13092/strlpad--pad-string-to-the-left
 local function str_padend(str, len, char)
 	if char == nil then char = ' ' end

worldeditadditions_core/utils/node_identification.lua

@@ -1,5 +1,7 @@
 local wea_c =  worldeditadditions_core
 
+--- 
+-- @module	worldeditadditions_core
 
 local node_id_air = minetest.get_content_id("air")
 local node_id_ignore = minetest.get_content_id("ignore")
@@ -104,6 +106,7 @@ function wea_c.register_sapling_alias_many(tbl)
 	end
 	return true
 end
+
 --- Returns the current key ⇒ value table of sapling names and aliases.
 -- @return	table
 function wea_c.get_all_sapling_aliases()

worldeditadditions_core/utils/nodes.lua

@@ -1,5 +1,9 @@
 local wea_c =  worldeditadditions_core
 
+--- 
+-- @module	worldeditadditions_core
+
+
 --- Makes an associative table of node_name => weight into a list of node ids.
 -- Node names with a higher weight are repeated more times.
 function wea_c.make_weighted(tbl)

worldeditadditions_core/utils/numbers.lua

@@ -1,17 +1,27 @@
 local wea_c = worldeditadditions_core
+---
+-- @module	worldeditadditions_core
 
--- From http://lua-users.org/wiki/SimpleRound
+--- Rounds a number to a given number of decimal places.
+-- @source http://lua-users.org/wiki/SimpleRound
+-- @param	num					number	The number to round.
+-- @param	numDecimalPlaces 	number	The number of decimal places to round to. Should be an integer greater than or equal to 0.
 function wea_c.round(num, numDecimalPlaces)
 	local mult = 10^(numDecimalPlaces or 0)
 	return math.floor(num * mult + 0.5) / mult
 end
 
+--- Calculates the length of the hypoentuse of a right-angled triangle.
+-- TODO: Document this function
 function wea_c.hypotenuse(x1, y1, x2, y2)
 	local xSquare = (x1 - x2) ^ 2;
 	local ySquare = (y1 - y2) ^ 2;
 	return math.sqrt(xSquare + ySquare);
 end
 
+--- Adds up all the numbers in the given list
+-- @param	number[]	The list of numbers to add.
+-- @returns	number		The sum total of all the numbers in the given list.
 function wea_c.sum(list)
 		if #list == 0 then return 0 end
 	local sum = 0

worldeditadditions_core/utils/player.lua

@@ -1,5 +1,11 @@
 local wea_c = worldeditadditions_core
 local v3 = worldeditadditions_core.Vector3
+
+---
+-- @module	worldeditadditions_core
+
+
+
 --- Returns the player's position (at leg level).
 -- @param	name	string	The name of the player to return facing direction of.
 -- @return	vector	Returns position.

worldeditadditions_core/utils/raycast_adv.lua

@@ -1,6 +1,12 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
+
+---
+-- @module	worldeditadditions_core
+
 --- Raycasts to find a node in the direction the given player is looking.
+-- 
+-- This function is not currently aware of custom hitboxes.
 -- @param	player			Player	The player object to raycast from.
 -- @param	maxdist			number	The maximum distance to raycast.
 -- @param	skip_liquid		bool	Whether to skip liquids when raycasting.

worldeditadditions_core/utils/set.lua

@@ -1,6 +1,6 @@
---- Sets for lua!
+--= Sets for lua!
 -- local Set = {}
---- Option 1:
+--= Option 1:
 -- Set.__index = Set
 -- Set.__newindex = function(tbl, key, value)
 -- 	if not tbl.__protected[key] then
@@ -18,6 +18,9 @@
 -- }
 
 --- Option 2:
+
+--- Set implementation for Lua.
+-- @class worldeditadditions_core.Set
 local Set = {}
 Set.__index = Set
 Set.__newindex = function(tbl, key, value)

worldeditadditions_core/utils/terrain/apply_heightmap_changes.lua

@@ -1,6 +1,10 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
+---
+-- @module worldeditadditions_core.terrain
+
+
 --- Applies changes to a heightmap to a Voxel Manipulator data block.
 -- @param	pos1	vector		Position 1 of the defined region
 -- @param	pos2	vector		Position 2 of the defined region

worldeditadditions_core/utils/terrain/calculate_normals.lua

@@ -1,6 +1,8 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
+---
+-- @module worldeditadditions_core.terrain
 
 --- Calculates a normal map for the given heightmap.
 -- Caution: This method (like worldeditadditions.make_heightmap) works on

worldeditadditions_core/utils/terrain/calculate_slopes.lua

@@ -1,6 +1,8 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
+--- 
+-- @module worldeditadditions_core.terrain
 
 --- Converts a 2d heightmap into slope values in radians.
 -- Convert a radians to degrees by doing (radians*math.pi) / 180 for display,

worldeditadditions_core/utils/terrain/init.lua

@@ -1,5 +1,7 @@
 local wea_c = worldeditadditions_core
 
+--- Functions for working with 2D terrain maps.
+-- @namespace worldeditadditions_core.terrain
 local terrain = {
 	make_heightmap = dofile(wea_c.modpath.."/utils/terrain/make_heightmap.lua"),
 	calculate_normals = dofile(wea_c.modpath.."/utils/terrain/calculate_normals.lua"),

worldeditadditions_core/utils/terrain/make_heightmap.lua

@@ -1,6 +1,8 @@
 local wea_c = worldeditadditions_core
 local Vector3 = wea_c.Vector3
 
+---
+-- @module worldeditadditions_core.terrain
 
 --- Given a manip object and associates, generates a 2D x/z heightmap.
 -- Note that pos1 and pos2 should have already been pushed through