chore: start improving doc

sonic-radiance.love/birb/utils/datas.lua

@@ -1,4 +1,4 @@
--- loveutils.datas : simple functions for data manipulation.
+--- loveutils.datas : simple functions for data manipulation.
 
 --[[
   Copyright © 2021 Kazhnuz
@@ -26,11 +26,17 @@ local DataUtils = {}
 local DATADIR = "datas"
 local GAMEDATADIR = "gamedata"
 
+--- Verify if a name correspond to a lua file
+---@param name string the filename you want to test
+---@return boolean isLua if the filename finish by .lua
 function DataUtils.isLuaFile(name)
   local extension = name:sub(#name - 3, #name)
   return (extension == ".lua")
 end
 
+--- Transform a lua filename to a module name
+---@param luaFile string the filename you want to transform
+---@return boolean moduleName the module name
 function DataUtils.luaFileToModule(luaFile)
   if (DataUtils.isLuaFile(luaFile)) then
     return luaFile:sub(1, #luaFile - 4)
@@ -39,6 +45,9 @@ function DataUtils.luaFileToModule(luaFile)
   end
 end
 
+--- Transform a list of lua filename to a list of module name
+---@param luaFileList table the filename list you want to transform
+---@return table moduleList the module name list
 function DataUtils.luaFileListToModuleList(luaFileList)
   local moduleList = {}
   for i,luaFile in ipairs(luaFileList) do
@@ -47,10 +56,18 @@ function DataUtils.luaFileListToModuleList(luaFileList)
   return moduleList
 end
 
+--- Use "require" on a a composited filename
+---@param parent string the parent filename
+---@param filename string the filename of the file
+---@return any data the content of the lua file
 function DataUtils.require(parent, filename)
   return require(DataUtils.concatFolder(parent, filename, true))
 end
 
+--- Require and copy the content of a lua file 
+--- It's mostly used for lua file containing data, for not having to copy their data
+---@param filepath string the filepath of the file
+---@return table data the copied content of the lua file
 function DataUtils.copy(filepath)
   local orig = require(filepath)
   local orig_type = type(orig)
@@ -67,6 +84,11 @@ function DataUtils.copy(filepath)
 end
 
 
+--- Require and copy the content of a lua file from it's parent folder
+--- It's mostly used for lua file containing data, for not having to copy their data
+---@param parent string the path of the parent
+---@param filename string the filename of the file
+---@return table data the copied content of the lua file
 function DataUtils.copyDataset(parent, filename)
   local orig = DataUtils.require(parent, filename)
   local orig_type = type(orig)
@@ -82,18 +104,33 @@ function DataUtils.copyDataset(parent, filename)
   return copy
 end
 
+--- Get a data directory path from the gamedata dir
+---@param folder string the folder name
+---@param lua boolean if we are dealing with lua modules
+---@return string path the data directory path
 function DataUtils.concatDataFolder(folder, lua)
   return DataUtils.concatFolder(DataUtils.getGameDataDir(lua), folder, lua)
 end
 
+--- Get the game data directory
+---@param lua boolean if we are dealing with lua modules
+---@return string path the gamedirectory path
 function DataUtils.getGameDataDir(lua)
   return DataUtils.concatFolder(DATADIR, GAMEDATADIR, lua)
 end
 
+--- Concat a folder path
+---@param parent string the path of the parent folder
+---@param filename string the name of the element you want to concat to the path
+---@param lua boolean if we are dealing with lua modules
+---@return string path the path
 function DataUtils.concatFolder(parent, filename, lua)
   return parent .. DataUtils.sep(lua) .. filename
 end
 
+--- Return the separater character for lua modules or filesystem pathname
+---@param lua boolean if we are dealing with lua modules
+---@return string sep the separator
 function DataUtils.sep(lua)
   if (lua) then
     return "."

sonic-radiance.love/birb/utils/math.lua

@@ -1,4 +1,4 @@
--- loveutils.math : easy to use functions for mathematics and geometry.
+--- loveutils.math : easy to use functions for mathematics and geometry.
 
 --[[
   Copyright © 2019 Kazhnuz

sonic-radiance.love/birb/utils/table.lua

@@ -23,6 +23,10 @@
 
 local Table = {}
 
+--- Get the sum of a liste of number
+---@param table table the table which you want to find if it contain the content
+---@param content any the content that you want to find in the table
+---@return boolean contain if the table contain the content
 function Table.contain(table, content)
   for k, v in ipairs(table) do
     if (v == content) then
@@ -32,6 +36,9 @@ function Table.contain(table, content)
   return false
 end
 
+--- Get the table in form of a string
+---@param table table the table which you want to transform into a string
+---@return string string the string created from the table
 function Table.toString(table)
   local string = "{"
   for key, value in pairs(table) do
@@ -52,6 +59,9 @@ function Table.toString(table)
   return string .. "}"
 end
 
+--- Clone a table
+---@param table1 table the table to clone
+---@return table returnTable the cloned table
 function Table.clone(table1)
   local returnTable = {}
   for key, value in pairs(table1) do
@@ -60,6 +70,10 @@ function Table.clone(table1)
   return returnTable
 end
 
+--- Merge two list
+---@param table1 table the first list to merge
+---@param table2 table the list that you want to merge to the first
+---@return table table1 the first list, merged with the second
 function Table.mergeList(table1, table2)
   for i, value in ipairs(table2) do
     table.insert(table1, value)
@@ -67,6 +81,10 @@ function Table.mergeList(table1, table2)
   return table1
 end
 
+--- Merge two table
+---@param table1 table the first table to merge
+---@param table2 table the table that you want to merge to the first
+---@return table table1 the first table, merged with the second
 function Table.merge(table1, table2)
   for key, value in pairs(table2) do
     table1[key] = value
@@ -74,6 +92,10 @@ function Table.merge(table1, table2)
   return table1
 end
 
+--- Reduce a list with a function
+---@param list table the list you want to reduce
+---@param fn function a function to apply to the whole list. Args: the first reduced list & the current value
+---@return any acc the result of the reducing
 function Table.reduce(list, fn)
   local acc
   for k, v in ipairs(list) do
@@ -86,6 +108,9 @@ function Table.reduce(list, fn)
   return acc
 end
 
+--- Get the sum of a liste of number
+---@param table table the list to parse into an sum
+---@return number sum the sum of the table
 function Table.sum(table)
   local sum = 0
   for _, v in pairs(table) do
@@ -95,11 +120,14 @@ function Table.sum(table)
   return sum
 end
 
+--- Get the average of a liste of number
+---@param table table the list to parse into an average
+---@return number average the average of the table
 function Table.average(table)
   return Table.sum(table) / #table
 end
 
---Parse a basic list into a structured table. Return an error if the number of arguments is not the same
+--- Parse a basic list into a structured table. Return an error if the number of arguments is not the same
 ---@param table table the list to parse into a table
 ---@param structure table the structure to create the table : each name correspond to an attribute of the parsed table
 ---@param nullableNbr integer the number of nullable argument (at the end of the functions) (can be null)