From 9d47dcbcf3da3fefbc754c695c3d81b1c8126522 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Thu, 3 Aug 2023 14:16:14 +0100 Subject: [PATCH] comments: update --- worldeditadditions_core/utils/bit.lua | 19 ++++++++++++------- worldeditadditions_core/utils/chaikin.lua | 6 ++++++ worldeditadditions_core/utils/inspect.lua | 9 +++++++++ worldeditadditions_core/utils/io.lua | 4 ++++ .../utils/lru_benchmark.lua | 2 +- .../utils/node_identification.lua | 3 +++ worldeditadditions_core/utils/nodes.lua | 4 ++++ worldeditadditions_core/utils/numbers.lua | 12 +++++++++++- worldeditadditions_core/utils/player.lua | 6 ++++++ worldeditadditions_core/utils/raycast_adv.lua | 6 ++++++ worldeditadditions_core/utils/set.lua | 7 +++++-- .../utils/terrain/apply_heightmap_changes.lua | 4 ++++ .../utils/terrain/calculate_normals.lua | 2 ++ .../utils/terrain/calculate_slopes.lua | 2 ++ .../utils/terrain/init.lua | 2 ++ .../utils/terrain/make_heightmap.lua | 2 ++ 16 files changed, 79 insertions(+), 11 deletions(-) diff --git a/worldeditadditions_core/utils/bit.lua b/worldeditadditions_core/utils/bit.lua index fdde798..71bce14 100644 --- a/worldeditadditions_core/utils/bit.lua +++ b/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 diff --git a/worldeditadditions_core/utils/chaikin.lua b/worldeditadditions_core/utils/chaikin.lua index 6fdb82e..b01ced8 100644 --- a/worldeditadditions_core/utils/chaikin.lua +++ b/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. diff --git a/worldeditadditions_core/utils/inspect.lua b/worldeditadditions_core/utils/inspect.lua index d5ed030..e981180 100644 --- a/worldeditadditions_core/utils/inspect.lua +++ b/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 diff --git a/worldeditadditions_core/utils/io.lua b/worldeditadditions_core/utils/io.lua index 4d83589..a1c8bde 100644 --- a/worldeditadditions_core/utils/io.lua +++ b/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) diff --git a/worldeditadditions_core/utils/lru_benchmark.lua b/worldeditadditions_core/utils/lru_benchmark.lua index 4477c70..112cadf 100644 --- a/worldeditadditions_core/utils/lru_benchmark.lua +++ b/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 diff --git a/worldeditadditions_core/utils/node_identification.lua b/worldeditadditions_core/utils/node_identification.lua index f93e8b9..f5c0c53 100644 --- a/worldeditadditions_core/utils/node_identification.lua +++ b/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() diff --git a/worldeditadditions_core/utils/nodes.lua b/worldeditadditions_core/utils/nodes.lua index 79fb104..c869829 100644 --- a/worldeditadditions_core/utils/nodes.lua +++ b/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) diff --git a/worldeditadditions_core/utils/numbers.lua b/worldeditadditions_core/utils/numbers.lua index d7a9832..cd649c1 100644 --- a/worldeditadditions_core/utils/numbers.lua +++ b/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 diff --git a/worldeditadditions_core/utils/player.lua b/worldeditadditions_core/utils/player.lua index 34598f1..5483a0f 100644 --- a/worldeditadditions_core/utils/player.lua +++ b/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. diff --git a/worldeditadditions_core/utils/raycast_adv.lua b/worldeditadditions_core/utils/raycast_adv.lua index b8c3705..6a3618d 100644 --- a/worldeditadditions_core/utils/raycast_adv.lua +++ b/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. diff --git a/worldeditadditions_core/utils/set.lua b/worldeditadditions_core/utils/set.lua index d5ea57d..c5d80d2 100644 --- a/worldeditadditions_core/utils/set.lua +++ b/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) diff --git a/worldeditadditions_core/utils/terrain/apply_heightmap_changes.lua b/worldeditadditions_core/utils/terrain/apply_heightmap_changes.lua index 944fd93..5098b81 100644 --- a/worldeditadditions_core/utils/terrain/apply_heightmap_changes.lua +++ b/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 diff --git a/worldeditadditions_core/utils/terrain/calculate_normals.lua b/worldeditadditions_core/utils/terrain/calculate_normals.lua index 8272a09..b9036e5 100644 --- a/worldeditadditions_core/utils/terrain/calculate_normals.lua +++ b/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 diff --git a/worldeditadditions_core/utils/terrain/calculate_slopes.lua b/worldeditadditions_core/utils/terrain/calculate_slopes.lua index e4fd99d..a1689ff 100644 --- a/worldeditadditions_core/utils/terrain/calculate_slopes.lua +++ b/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, diff --git a/worldeditadditions_core/utils/terrain/init.lua b/worldeditadditions_core/utils/terrain/init.lua index 3952f43..8328629 100644 --- a/worldeditadditions_core/utils/terrain/init.lua +++ b/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"), diff --git a/worldeditadditions_core/utils/terrain/make_heightmap.lua b/worldeditadditions_core/utils/terrain/make_heightmap.lua index 1669f27..7fb36bc 100644 --- a/worldeditadditions_core/utils/terrain/make_heightmap.lua +++ b/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