From 55d33c33d926fe20271039ab6413ca97d6371f65 Mon Sep 17 00:00:00 2001
From: FatalErr42O <58855799+FatalError42O@users.noreply.github.com>
Date: Mon, 23 Dec 2024 13:01:41 -0800
Subject: [PATCH] fix docs

---
 binary.lua    | 52 ++++++++++++++++++++++++++++-----------------------
 mod_utils.lua | 44 ++++++++++++++++++++++++++++++++++---------
 paths.lua     | 23 ++++++++++++++++-------
 3 files changed, 80 insertions(+), 39 deletions(-)

diff --git a/binary.lua b/binary.lua
index 2c9f98f..4759bb6 100644
--- a/binary.lua
+++ b/binary.lua
@@ -1,5 +1,5 @@
 --- read and write (little endian) binary.
---- located in `leef.binary`.
+-- This is apart of the [LEEF-filesystem](https://github.com/Luanti-Extended-Engine-Features/LEEF-filesystem) module.
 --@module binary
 
 local assert, math_huge, math_frexp, math_floor
@@ -14,9 +14,30 @@ local positive_nan = negative_nan ^ 1
 -- @see read_byte
 
 
+--- expected function inputs.
+-- functions will expect either a `read_byte` or `write_byte` function as inputs
+-- @section input
+
+--- `read_byte` is a param name which refers to a function which reads the next byte- returning a whole number between 0-255.
+--
+-- 	function byte()
+--		left = left - 1
+--		return assert(file_handle:read(1):byte())
+--		--reads the next chracter, and converts it to a "numerical code" using string.byte()
+-- 		--it's important that this function moves forward in the file stream (as :read(1) does)
+-- 	end
+-- @function read_byte
+-- @return a bytecode (an int between 0 and 255.)
+
+--- `write_byte` is similar to read_byte, however it is given an input and expected to write it to the file.
+-- (example needed)
+-- @function write_byte
+
+
 --- read an IEEE 754 single precision (32-bit) floating point number
 -- @function read_single
 -- @param function @{read_byte}
+-- @return number
 function leef.binary.read_single(read_byte)
 	-- First read the mantissa
 	local mantissa = read_byte() / 0x100
@@ -54,6 +75,7 @@ end
 --- read an IEEE 754 double-precision (64-bit) floating point number
 -- @function read_double
 -- @param function @{read_byte}
+-- @return number
 function leef.binary.read_double(read_byte)
 	-- First read the mantissa
 	local mantissa = 0
@@ -91,6 +113,7 @@ end
 -- @function read_uint
 -- @param function @{read_byte}
 -- @param int length in bytes of unsigned integer
+-- @return unit number
 function leef.binary.read_uint(read_byte, bytes)
 	local factor = 1
 	local uint = 0
@@ -105,6 +128,7 @@ end
 -- @function read_uint
 -- @param function @{read_byte}
 -- @param int length in bytes of integer
+-- @return int number
 function leef.binary.read_int(read_byte, bytes)
 	local uint = leef.binary.read_uint(read_byte, bytes)
 	local max = 0x100 ^ bytes
@@ -115,9 +139,10 @@ function leef.binary.read_int(read_byte, bytes)
 end
 
 --- writing binary
--- documentation needed
--- @section write
--- @fixme add documentation
+-- @function write_uint
+-- @param write_byte @{write_byte}
+-- @tparam int unit unit to write
+-- @tparam int bytes number of bytes to right
 function leef.binary.write_uint(write_byte, uint, bytes)
 	for _ = 1, bytes do
 		write_byte(uint % 0x100)
@@ -273,22 +298,3 @@ function leef.binary.fround(number)
 	end
 	return sign * powexp * (leading + mantissa / 0x800000)
 end
-
---- expected function inputs.
--- functions will expect either a `read_byte` or `write_byte` function as inputs
--- @section input
-
---- `read_byte` is a param name which refers to a function which reads the next byte- returning a whole number between 0-255.
---
--- 	function byte()
---		left = left - 1
---		return assert(file_handle:read(1):byte())
---		--reads the next chracter, and converts it to a "numerical code" using string.byte()
--- 		--it's important that this function moves forward in the file stream (as :read(1) does)
--- 	end
--- @function read_byte
--- @return a bytecode (an int between 0 and 255.)
-
---- `write_byte` is similar to read_byte, however it is given an input and expected to write it to the file.
--- (example needed)
--- @function write_byte
\ No newline at end of file
diff --git a/mod_utils.lua b/mod_utils.lua
index 43ddc3a..d3958e7 100644
--- a/mod_utils.lua
+++ b/mod_utils.lua
@@ -1,24 +1,33 @@
+--- mod data and information utilities.
+-- not super useful, might be deprecated and put into leef.paths namespace in the future
+--
+-- This is apart of the [LEEF-filesystem](https://github.com/Luanti-Extended-Engine-Features/LEEF-filesystem) module.
+-- @module utils
 
-function leef.utils.get_resource(modname, resource, ...)
+--this isn't even recursive I have no idea why this even fucking exists and it makes me want to kill myself, thanks.
+local function get_resource(modname, resource)
 	if not resource then
 		resource = modname
 		modname = minetest.get_current_modname()
 	end
-	return table.concat({minetest.get_modpath(modname), resource, ...}, "/")
+	return table.concat({minetest.get_modpath(modname), resource}, "/")
 end
 local function trim_spacing(text)
 	return text:match"^%s*(.-)%s*$"
 end
---I will add a file reading lib eventually...
+
 local read_file = function(mod, filename)
-    local filepath = leef.utils.get_resource(mod, filename)
-    local file, err = io.open(filename, "r")
+    local filepath = get_resource(mod, filename)
+    local file, err = io.open(filepath, "r")
     if file == nil then return nil, err end
     local content = file:read"*a"
     file:close()
+	return content
 end
 
 local mod_info
+--- gets mod info
+-- @return table containing all mods and their `description`, `depends`, `optional_depends`, and `name`. This table will throw an error if attempts are made to edit its contents.
 function leef.utils.get_mod_info()
 	if mod_info then return mod_info end
 	mod_info = {}
@@ -26,7 +35,7 @@ function leef.utils.get_mod_info()
 	local modnames = minetest.get_modnames()
 	for _, mod in pairs(modnames) do
 		local info
-		local mod_conf = Settings(leef.utils.get_resource(mod, "mod.conf"))
+		local mod_conf = Settings(get_resource(mod, "mod.conf"))
 		if mod_conf then
 			info = {}
 			mod_conf = mod_conf:to_table()
@@ -61,17 +70,34 @@ function leef.utils.get_mod_info()
 			info.name = mod
 		end
 		mod_info[mod] = info
+		setmetatable(info, {
+			__newindex = function()
+				error("attempt to edit mod_info sub-table for mod: `"..info.name.."`")
+			end
+		})
 	end
+	setmetatable(mod_info, {
+		__newindex = function()
+			error("attempt to edit mod_info table")
+		end
+	})
 	return mod_info
 end
-local mod_load_order
+
+--- get the load order of mods and their status
+-- @treturn list of tables which contains `status = "loaded" | loading`, and inherits all other fields from the tables returned in `get_mod_info()`. This can be edited.
 function leef.utils.get_mod_load_order()
-	if mod_load_order then return mod_load_order end
-	mod_load_order = {}
+	local mod_load_order = {}
 	local mod_info = leef.utils.get_mod_info()
 	-- If there are circular soft dependencies, it is possible that a mod is loaded, but not in the right order
 	-- TODO somehow maximize the number of soft dependencies fulfilled in case of circular soft dependencies
 	local function load(mod)
+		mod = {
+			description = mod.description,
+			name = mod.name,
+			depends = mod.depends,
+			optional_depends = mod.optional_depends
+		}
 		if mod.status == "loaded" then
 			return true
 		end
diff --git a/paths.lua b/paths.lua
index 14adb26..1dcf7b0 100644
--- a/paths.lua
+++ b/paths.lua
@@ -1,10 +1,10 @@
---felt this was big enough that it practically deserved it's own file.
--- TODO support for server texture packs (and possibly client TPs in singleplayer?)
-
---- mod utilities
---find the paths
---- find mod information
+--- used to find mod media and modpath information
+--
+-- needs dynamic send media support...
+--
+-- This is apart of the [LEEF-filesystem](https://github.com/Luanti-Extended-Engine-Features/LEEF-filesystem) module.
 -- @module paths
+
 local media_foldernames = {"textures", "sounds", "media", "models", "locale"}
 local media_extensions = {
 	-- Textures
@@ -23,6 +23,15 @@ end
 for i, v in pairs(media_extensions) do
     media_extensions[v] = true
 end
+
+local function get_resource(modname, resource)
+	if not resource then
+		resource = modname
+		modname = minetest.get_current_modname()
+	end
+	return table.concat({minetest.get_modpath(modname), resource}, "/")
+end
+
 local function collect_media(modname)
 	local media = {}
 	local function traverse(folderpath)
@@ -43,7 +52,7 @@ local function collect_media(modname)
 		end
 	end
 	for _, foldername in ipairs(media_foldernames) do -- order matters!
-		traverse(leef.utils.get_resource(modname, foldername))
+		traverse(get_resource(modname, foldername))
 	end
 	return media
 end