Merge pull request #8 from gesslar/redoing-docs

Redoing docs

library/date.lua

@@ -0,0 +1,21 @@
+---@meta DateClass
+
+------------------------------------------------------------------------------
+-- DateClass
+------------------------------------------------------------------------------
+
+if false then -- ensure that functions do not get defined
+
+  ---@class DateClass
+
+  ---Converts a number of seconds into a human-readable string. By default, the
+  ---result is returned as a table of three strings. However, if the `as_string`
+  ---parameter is provided, the result is returned as a single string.
+  ---
+  ---@name shms
+  ---@param seconds number - The number of seconds to convert.
+  ---@param as_string boolean? - Whether to return the result as a string.
+  ---@return string[]|string # The resulting string or table of strings.
+  function date.shms(seconds, as_string) end
+
+end

library/glass.lua

@@ -0,0 +1,28 @@
+---@meta Glass
+
+------------------------------------------------------------------------------
+-- Glass
+------------------------------------------------------------------------------
+
+if false then -- ensure that functions do not get defined
+
+  ---@class Glass
+
+  ---Register a class with the Glu framework.
+  ---
+  ---The following options are available:
+  ---
+  ---* `class_name` string - The name of the class, usually in the form of `NameClass`.
+  ---* `name` string - The name of the class, usually in the form of `name`.
+  ---* `inherit_from` string? - The class to inherit from, in the form of the class's `name`.
+  ---* `dependencies` string[] - The dependencies of the class, in the form of the class's `name` .
+  ---* `inherit` table<string, function> - The functions to inherit, in the form of `function_name = function(self, ...) end`.
+  ---* `setup` function - The setup function, in the form of `function(self, ...) end`.
+  ---* `valid` function - The valid function, in the form of `function(self, ...) end`.
+  ---
+  ---@name register
+  ---@param class_opts table - The class options.
+  ---@return Glass # The class.
+  function Glass.register(class_opts) end
+
+end

library/glu.lua

@@ -0,0 +1,90 @@
+---@meta Glu
+
+------------------------------------------------------------------------------
+-- Glu
+------------------------------------------------------------------------------
+
+if false then -- ensure that functions do not get defined
+
+  ---@class Glu
+
+  ---Instantiate a new Glu instance. Can be invoked by its class name or
+  ---by the `new` function.
+  ---
+  ---@example
+  ---```lua
+  ---local glu = Glu.new("MyPackage", "MyModule")
+  ---local glu = Glu("MyPackage", "MyModule")
+  ---```
+  ---
+  ---@name new
+  ---@param package_name string - The name of the package to which this module belongs.
+  ---@param module_dir_name string? - The directory name inside the package directory where the modules are located.
+  ---@return Glu # A new Glu instance.
+  function Glu.new(package_name, module_dir_name) end
+
+  ---Generate a unique identifier, producing a version 4 UUID.
+  ---
+  ---@name id
+  ---@return string # A unique identifier.
+  ---@example
+  ---```lua
+  ---local id = Glu.id()
+  ---```
+  ---@name id
+  function Glu.id() end
+
+  ---Get all glasses.
+  ---
+  ---@name get_glasses
+  ---@return Glass[] # A table of glasses.
+  ---@example
+  ---```lua
+  ---local glasses = Glu.get_glasses()
+  ---```
+  ---
+  function Glu.get_glasses() end
+
+  ---Get all glass names.
+  ---
+  ---@name get_glass_names
+  ---@return string[] # A table of glass names.
+  ---@example
+  ---```lua
+  ---local glass_names = Glu.get_glass_names()
+  ---```
+  ---
+  function Glu.get_glass_names() end
+
+  ---Get a glass by name.
+  ---
+  ---@name get_glass
+  ---@param glass_name string - The name of the glass to retrieve.
+  ---@return Glass? # The glass, or nil if it does not exist.
+  ---@example
+  ---```lua
+  ---local glass = Glu.get_glass("MyGlass")
+  ---```
+  ---
+  function Glu.get_glass() end
+
+  ---Check if a glass exists.
+  ---
+  ---@name has_glass
+  ---@param glass_name string - The name of the glass to check for.
+  ---@return boolean # True if the glass exists, false otherwise.
+  ---@example
+  ---```lua
+  ---local exists = Glu.has_glass("MyGlass")
+  ---```
+  ---
+  function Glu.has_glass(glass_name) end
+
+  ---Get the last traceback line. Used for validation functions, or any
+  ---time you need to get the last line of a traceback. Also available
+  ---via the `v` table from the anchor.
+  ---
+  ---@name get_last_traceback_line
+  ---@return string # The last traceback line.
+  function Glu.get_last_traceback_line() end
+end

library/number.lua

@@ -0,0 +1,200 @@
+---@meta NumberClass
+
+------------------------------------------------------------------------------
+-- NumberClass
+------------------------------------------------------------------------------
+
+if false then -- ensure that functions do not get defined
+
+  ---@class NumberClass
+
+  ---Calculates the average of a list of numbers. The input can be a single
+  ---table of numbers or multiple numbers as individual arguments.
+  ---
+  ---@name average
+  ---@param ... number|number[] - The numbers to average.
+  ---@return number # The average of the numbers.
+  function number.average(...) end
+
+  ---Clamps a number between a minimum and maximum value.
+  ---
+  ---@name clamp
+  ---@param num number - The number to clamp.
+  ---@param min number - The minimum value.
+  ---@param max number - The maximum value.
+  ---@return number # The clamped number.
+  function number.clamp(num, min, max) end
+
+  ---Constrains a number to a certain precision.
+  ---
+  ---@name constrain
+  ---@param num number - The number to constrain.
+  ---@param precision number - The precision (e.g., 0.1, 0.01, etc.).
+  ---@return number # The constrained number.
+  function number.constrain(num, precision) end
+
+  ---Checks if two numbers are approximately equal, given a percentage tolerance.
+  ---
+  ---@name is_approximate
+  ---@param a number - The first number.
+  ---@param b number - The second number.
+  ---@param percent_tolerance number - The percentage tolerance.
+  ---@return boolean # Whether the numbers are approximately equal.
+  function number.is_approximate(a, b, percent_tolerance) end
+
+  ---Checks if a number is between a minimum and maximum value.
+  ---
+  ---@name is_between
+  ---@param num number - The number to check.
+  ---@param min number - The minimum value.
+  ---@param max number - The maximum value.
+  ---@return boolean # Whether the number is between the minimum and maximum values.
+  function number.is_between(num, min, max) end
+
+  ---Linearly interpolates between two values, easing in at the beginning.
+  ---
+  ---@name lerp_ease_in
+  ---@param start number - The starting value.
+  ---@param end_val number - The ending value.
+  ---@param t number - The interpolation factor.
+  ---@return number # The interpolated value.
+  function number.lerp_ease_in(start, end_val, t) end
+
+  ---Linearly interpolates between two values, easing out at the end.
+  ---
+  ---@name lerp_ease_out
+  ---@param start number - The starting value.
+  ---@param end_val number - The ending value.
+  ---@param t number - The interpolation factor.
+  ---@return number # The interpolated value.
+  function number.lerp_ease_out(start, end_val, t) end
+
+  ---Linearly interpolates between two values, smoothly easing in and out.
+  ---
+  ---@name lerp_smooth
+  ---@param start number - The starting value.
+  ---@param end_val number - The ending value.
+  ---@param t number - The interpolation factor.
+  ---@return number # The interpolated value.
+  function number.lerp_smooth(start, end_val, t) end
+
+  ---Linearly interpolates between two values, smoothly easing in and out.
+  ---
+  ---@name lerp_smoother
+  ---@param start number - The starting value.
+  ---@param end_val number - The ending value.
+  ---@param t number - The interpolation factor.
+  ---@return number # The interpolated value.
+  function number.lerp_smoother(start, end_val, t) end
+
+  ---Linearly interpolates between two values.
+  ---
+  ---@name lerp
+  ---@param a number - The starting value.
+  ---@param b number - The ending value.
+  ---@param t number - The interpolation factor.
+  ---@return number # The interpolated value.
+  function number.lerp(a, b, t) end
+
+  ---Maps a value from one range to another. The input value is scaled to the
+  ---output range.
+  ---
+  ---@name map
+  ---@param value number - The value to map.
+  ---@param in_min number - The minimum value of the input range.
+  ---@param in_max number - The maximum value of the input range.
+  ---@param out_min number - The minimum value of the output range.
+  ---@param out_max number - The maximum value of the output range.
+  ---@return number # The mapped value.
+  function number.map(value, in_min, in_max, out_min, out_max) end
+
+  ---Returns the maximum value from a list of numbers. The input can be a single
+  ---table of numbers or multiple numbers as individual arguments.
+  ---
+  ---@name max
+  ---@param ... number|number[] - The numbers to compare.
+  ---@return number # The maximum value.
+  function number.max(...) end
+
+  ---Returns the minimum value from a list of numbers. The input can be a single
+  ---table of numbers or multiple numbers as individual arguments.
+  ---
+  ---@name min
+  ---@param ... number|number[] - The numbers to compare.
+  ---@return number # The minimum value.
+  function number.min(...) end
+
+  ---Normalizes a number to a range between 0 and 1.
+  ---
+  ---@name normalize
+  ---@param num number - The number to normalize.
+  ---@param min number - The minimum value of the range.
+  ---@param max number - The maximum value of the range.
+  ---@return number # The normalized number.
+  function number.normalize(num, min, max) end
+
+  ---Calculates the percentage of the first value relative to the second value.
+  ---
+  ---@example
+  ---```lua
+  ---number.percent_of(5, 20)
+  ----- 5
+  ---```
+  ---@name percent_of
+  ---@param numerator number - The numerator of the percentage.
+  ---@param denominator number - The denominator of the percentage.
+  ---@param round_digits number? - The number of digits to round the result to.
+  ---@return number # The percentage of the numerator relative to the denominator.
+  function number.percent_of(numerator, denominator, round_digits) end
+
+  ---Returns the value of a percentage relative to a total.
+  ---
+  ---@example
+  ---```lua
+  ---number.percent(5, 20)
+  ----- 1
+  ---```
+  ---@name percent
+  ---@param percent number - The percentage
+  ---@param total number - The total value.
+  ---@param round_digits number? - The number of digits to round the result to.
+  ---@return number # The value of the percentage relative to the total.
+  function number.percent(percent, total, round_digits) end
+
+  ---Checks if a number is positive.
+  ---
+  ---@name positive
+  ---@param num number - The number to check.
+  ---@return boolean # Whether the number is positive.
+  function number.positive(num) end
+
+  ---Returns a random number between a minimum and maximum value.
+  ---
+  ---@example
+  ---```lua
+  ---number.random_clamp(1, 10)
+  ----- 5
+  ---```
+  ---@name random_clamp
+  ---@param min number - The minimum value.
+  ---@param max number - The maximum value.
+  ---@return number # A random number between the minimum and maximum values.
+  function number.random_clamp(min, max) end
+
+  ---Rounds a number to a certain precision.
+  ---
+  ---@name round
+  ---@param num number - The number to round.
+  ---@param digits number? - The number of digits to round to.
+  ---@return number # The rounded number.
+  function number.round(num, digits) end
+
+  ---Sums a list of numbers. The input can be a single table of numbers or
+  ---multiple numbers as individual arguments.
+  ---
+  ---@name sum
+  ---@param ... number|number[] - The numbers to sum.
+  ---@return number # The sum of the numbers.
+  function number.sum(...) end
+
+end

library/preferences.lua

@@ -0,0 +1,42 @@
+---@meta PreferencesClass
+
+------------------------------------------------------------------------------
+-- PreferencesClass
+------------------------------------------------------------------------------
+
+if false then -- ensure that functions do not get defined
+
+  ---@class PreferencesClass
+
+  --- Loads preferences from a file. If a package name is provided, it will be
+  --- used to construct the path. Otherwise, the file will be loaded from the
+  --- profile directory.
+  ---
+  ---@example
+  ---```lua
+  ---preferences.load("my_package", "settings", { default_value = 1 })
+  ---```
+  ---
+  --- @name load
+  --- @param pkg string? - The package name. (Optional. Default is nil.)
+  --- @param file string - The file name.
+  --- @param defaults table - The default values.
+  --- @return table # The loaded preferences.
+  function preferences.load() end
+
+  --- Saves preferences to a file. If a package name is provided, it will be
+  --- used to construct the path. Otherwise, the file will be saved to the
+  --- profile directory.
+  ---
+  --- @example
+  --- ```lua
+  --- preferences.save("my_package", "settings", { default_value = 1 })
+  --- ```
+  ---
+  --- @name save
+  --- @param pkg string? - The package name. (Optional. Default is nil.)
+  --- @param file string - The file name.
+  --- @param prefs table # The preferences to save.
+  function preferences.save() end
+
+end