fixed doc errors in b3d-reader

modlib/read_b3d.lua

@@ -1,4 +1,7 @@
 --- parse .b3d files into a lua table.
+--
+-- This is apart of the [LEEF-b3d](https://github.com/Luanti-Extended-Engine-Features/LEEF-b3d) module
+--
 -- note: capitlization of name indicates a "chunk" defined by the blitz3d format (see b3d_specification.txt)
 --@module b3d_reader
 
@@ -20,7 +23,7 @@ end
 --reads a model directly (based on name). Note that "node_only" abstracts chunks not necessary to finding the position/transform of a bone/node.
 
 --- read b3d models by their name. This simplifies read_from_stream.
--- @function leef.b3d_reader.read_model
+-- @function read_model
 -- @param modelname string, the name of model you are trying to read.
 -- @param node_only bool, specifies wether to ignore textures, meshes, or anything else. Use this if you're only trying to solve bone transforms.
 -- @return b3d table (documentation needed!)
@@ -68,14 +71,24 @@ end
 -- @field 8 "KEYS" keyframes
 -- @table chunks
 
+--- table which specifies a keyframe. This is apart of the node chunk
+--@field position position relative to parent {x,y,z}
+--@field rotation quaternion rotation {x,y,z,w}
+--@field scale scale of the node {x,y,z}
+--@table keyframe
+
+--- node paths
+-- a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node"
+--@field (...) node
+--@table node_paths
+
 --- read directly from file
--- @function leef.b3d_reader.read_from_stream
--- @param stream the file object (from the io library) to read from. Make sure you open it as "rb" (read binary.)
--- @param ignore_chunks a list of @{chunks} to be ignored (documentation needed)
--- @return @{BB3D} (documentation needed!)
+--@function read_from_stream
+--@param stream the file object (from the io library) to read from. Make sure you open it as "rb" (read binary.)
+--@param ignore_chunks a list of @{chunks} to be ignored (documentation needed)
+--@return @{BB3D} (documentation needed!)
 function leef.b3d_reader.read_from_stream(stream, ignore_chunks)
 	local left = 8
-
 	local ignored = {}
 	if ignore_chunks then
 		for i, v in pairs(ignore_chunks) do
@@ -160,10 +173,13 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks)
 	local node_chunk_types = {
 
 	}
+	--- chunks
+	--@section chunks
 
 	local chunk
 	local chunks = {
 		TEXS = function()
+
 			local textures = {}
 			while content() do
 				local tex = {}
@@ -295,12 +311,8 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks)
 			local bone = {
 				flags = flags
 			}
+			--see keyframe documentation
 			while content() do
-				--- table which specifies a keyframe
-				--@position position relative to parent {x,y,z}
-				--@rotation quaternion rotation {x,y,z,w}
-				--@scale = {x,y,z}
-				--@table keyframe
 				local frame = {}
 				--minetest uses a zero indexed frame system, so for consistency, we offset it by 1
 				frame.frame = int()-1
@@ -399,15 +411,15 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks)
 			end)
 			return node
 		end,
-		--- b3d table
-		-- note: in the b3d writer the node_paths field is ignored
-		-- @field node_paths all of the nodes in the model @{b3d_nodes}
-		-- @field node a table containing the root @{NODE} of the model.
-		-- @field textures @{TEXS} texture information
-		-- @field brushes @{BRUS} material information
-		-- @field version `{major=float, minor=float}` this functionally means nothing, but it's version information.
-		-- @table BB3D
 		BB3D = function()
+			--- b3d table
+			-- note: in the b3d writer the node_paths field is ignored
+			-- @field node_paths all of the nodes in the model @{b3d_nodes}
+			-- @field node a table containing the root @{NODE} of the model.
+			-- @field textures TEXS texture information. TEXS not currently documented as not currently useful for minetest purposes
+			-- @field brushes BRUS material information. BRUS not currently documented as not currently useful for minetest purposes
+			-- @field version `{major=float, minor=float}` this functionally means nothing, but it's version information.
+			-- @table BB3D
 			local version = int()
 			local self = {
 				version = {
@@ -476,6 +488,7 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks)
 	end
 
 	local self = chunk{BB3D = true}
+	-- see node_paths documentation
 	self.node_paths = {}
 	self.excluded_chunks = ignore_chunks and table.copy(ignore_chunks) or {}
 	assert(self.node, "no root node - model improperly exported. If using blender, ensure all objects are selected before exporting.")
@@ -483,9 +496,4 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks)
 
 	--b3d metatable unimplemented
 	return setmetatable(self, leef._b3d_metatable or {})
-end
-
---- node paths
--- a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node"
--- @field (...) node
--- @table node_paths
+end

modlib/to_gltf.lua

@@ -3,7 +3,7 @@
 --THIS FILE IS INACTIVE, VERY BROKEN
 
 
---possibly unreliable, appgurueu (creator) says:
+--appgurueu:
 -- B3D to glTF converter
 -- See https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
 --! Highly experimental; expect bugs!

modlib/write_b3d.lua

@@ -1,4 +1,7 @@
---- writes b3d models in the same format as outputted by the b3d reader module
+--- writes b3d models in the same format as outputted by the b3d reader modul
+--
+-- This is apart of the [LEEF-b3d](https://github.com/Luanti-Extended-Engine-Features/LEEF-b3d) module
+--
 --@module b3d_writer
 
 
@@ -218,7 +221,7 @@ local function write_rope(self)
 end
 
 --- output a string of binary in the blitz 3d format
--- @function leef.b3d_writer.write_string
+-- @function write_string
 -- @param self @{BB3D}
 -- @return string containing the binary file
 function leef.b3d_writer.write_string(self)
@@ -226,7 +229,7 @@ function leef.b3d_writer.write_string(self)
 end
 
 --- output in the blitz3d format file reference
--- @function leef.b3d_writer.write_model_to_file
+-- @function write_model_to_file
 -- @param self @{BB3D}
 -- @param stream io file object to write to
 function leef.b3d_writer.write_model_to_file(self, stream)

nodes.lua

@@ -1,6 +1,8 @@
 --- allows you to get information about nodes (bones or meshes) within a b3d table (generated with `b3d_reader`)
---- located in `leef.b3d_nodes`.
---- WARNING! leef_math must be present for this module to run!
+--
+-- This is apart of the [LEEF-b3d](https://github.com/Luanti-Extended-Engine-Features/LEEF-b3d) module
+--
+-- WARNING! This LEEF-b3d submodule depends on the [LEEF-math](https://github.com/Luanti-Extended-Engine-Features/LEEF-math)
 --@module b3d_nodes
 --@warning for this module leef_math is required, trying to use these functions without leef_math ran will error.
 
@@ -12,7 +14,6 @@ local mat4 = leef.math.mat4
 local quat = leef.math.quat
 
 --- get a node by it's name
--- @function leef.b3d_nodes.get_node_by_name
 -- @param self the b3d table (from b3d_reader)
 -- @param node_name the name of the node to fine
 -- @param is_bone (optional) bool to indicate wether the node is a bone or not (incase there's a mesh named the same thing). False will only return meshes and pivots, true will only return bones. Nil will return any.
@@ -45,7 +46,6 @@ end
 
 --- get the local "TRS" (translation, rotation, scale) of a bone in animation. This is used for global transformation calculations.
 --- quaternion is returned as a string indexed table because it needs to be a math object to be interpolated, also has to be usable anyway.
--- @function leef.b3d_nodes.get_animated_local_trs
 -- @param node table, the node from within a b3d table to read (as outputed by b3d_reader).
 -- @param target_frame float, the frame to find the TRS in, can be inbetween frames/keyframes (of course).
 -- @return `position` ordered table: {x, y, z}
@@ -90,7 +90,6 @@ end
 --param 3 (outputs) is either "rotation" or "transform"- determines what's calculated. You can use this if you dont want uncessary calculations. If nil outputs both
 
 --- get a node's global mat4 transform and rotation.
--- @function leef.b3d_nodes.get_node_global_transform
 -- @param node table, the node from within a b3d table to read (as outputed by `b3d_reader`).
 -- @param frame float, the frame to find the transform and rotation in.
 -- @param outputs (optional) string, either "1" or "2" where 1 will output the transform alone and 2 will output the rotation alone. Set to nil to return both.
@@ -137,7 +136,6 @@ end
 --Returns X, Y, Z. is_bone is optional, if "node" is the name of a node (and not the node table), parameter 1 (self) and parameter 3 (is_bone) is used to find it.
 
 --- find the position of a node in global model space.
---@function leef.b3d_nodes.get_node_global_position
 --@param self b3d table, (optional if node is a node table and not name)
 --@param node string or table, either the node from b3d table or a the name of the node to find.
 --@param is_bone (optional) if node is string, this is used to find it (see `get_node_by_name`)
@@ -156,7 +154,6 @@ function b3d_nodes.get_node_global_position(self, node, is_bone, frame)
     return transform[13], transform[14], transform[15]
 end
 --- find the global rotation of a node in model space.
---@function leef.b3d_nodes.get_node_rotation
 --@param self b3d table, (optional if node is a node table and not name)
 --@param node string or table, either the node from b3d table or a the name of the node to find.
 --@param is_bone (optional) if node is string, this is used to find it (see `get_node_by_name`)