🚧📝 Complete documentation

arcades/utils/Logger.lua

---- Add some useful functions to lualogging module.
--- @module utils.logging
+--- A logger class.
+--
+-- A class that can be used by any object to instanciate dedicated logger.
+-- See documentation of Python logging facility to see what I tried to
+-- achieve.
+--
+-- This class also contains a @{main_logger|default/main logger} as a
+-- static field for quick and dirty logging.
+-- @classmod utils.Logger
+-- @alias class
 -- @author Alexis BRENON <alexis.brenon@imag.fr>
 
 local torch = require('torch')
@@ -7,6 +15,28 @@ local torch = require('torch')
 local module = {}
 local class = torch.class('Logger', module)
 
+--- Fields
+-- @section field
+
+--- Name of the logger to identify it.
+-- @tfield string name
+
+--- Function used to format log message.
+-- @tfield function formatter
+
+--- Output stream used by the logger.
+-- @tfield io.file_descripton output
+
+--- Current logging level.
+-- @tfield integer level_value
+
+--- @section end
+
+--- Class constructor.
+-- @tparam string name @{name|Name} of the logger
+-- @param[opt=default_level_value] level Logging level (string or integer) to use
+-- @tparam[opt=timestamp_output] function formatter Function used to format log message
+-- @tparam[opt=default_output] io.file_descriptor output Stream to use as logger output
 function class:__init(name, level, formatter, output)
   self.name = name
   self.formatter = formatter or self.timestamp_output
@@ -14,6 +44,15 @@ function class:__init(name, level, formatter, output)
   self:set_level(level or class.default_level_value)
 end
 
+--- Public Methods
+-- @section public-methods
+
+--- Change logging level.
+--
+-- Change the current logging level to the given `level` witch can be passed as
+-- @{level_values|integer} or @{level_strings|string} values.
+-- @param level Logging level to use
+-- @return `self`
 function class:set_level(level)
   local int_level, str_level = self.get_levels(level)
   self.level_value = int_level
@@ -21,10 +60,38 @@ function class:set_level(level)
   return self
 end
 
+--- Get logging level.
+--
+-- Return current logging level as
+-- @{level_values|integer} and @{level_strings|string} values.
+-- @treturn integer Current logging integer value
+-- @treturn string Current logging string value
 function class:get_level()
   return self.get_levels(self.level_value)
 end
 
+--- Change the output.
+-- @tparam[opt=nil] string filename Log to the given file or `io.stdout` if `nil`
+function class:set_output(filename)
+  self:info("Updating log output: " .. filename or "stdout")
+  if filename then
+    self.output = io.open(filename, "a")
+  else
+    self.output = io.output
+  end
+end
+
+--- Log a message.
+--
+-- Generate a log message with the given `level`, and print it if current logging level allows it.
+--
+-- A function is also defined for each log level, using a lower cased version of @{level_strings} values.
+-- @usage logger:log("DEBUG", ...)
+-- -- equivalent to
+-- logger:debug(...)
+-- @param level Message level as @{level_values|integer} or @{level_strings|string} value.
+-- @param ... Data to format and log. See @_get_log_message.
+-- @return self
 function class:log(level, ...)
   local int_level, _ = self.get_levels(level)
   if int_level >= self.level_value then
@@ -35,6 +102,19 @@ function class:log(level, ...)
   return self
 end
 
+--- Print a progressing wheel.
+-- @warn This function is only available for the @{main_logger}.
+-- @tparam[opt] integer step Step number to display
+-- @function progress 
+
+--- Private Methods
+-- @section private-methods
+
+--- Build and format a log message.
+-- @tparam integer int_level Integer value of the level of the message
+-- @tparam string str_format Base string to format
+-- @param ... Values used for formatting
+-- @treturn string Formatted log message
 function class:_get_log_message(int_level, str_format, ...)
   local msg = str_format
   local str_level = self._get_level_string(int_level)
@@ -48,20 +128,36 @@ function class:_get_log_message(int_level, str_format, ...)
   return self:_format(str_level, msg)
 end
 
+--- Add logger informations to log message.
+-- @tparam string str_level String value of the message level
+-- @tparam string msg User log message
+-- @treturn string Logger formatted message
 function class:_format(str_level, msg)
   return self:formatter(str_level, msg)
 end
 
---- Change the output of the logging facilities.
--- @tparam[opt=nil] string filename Log to the given file or stdout if <code>nil</code>
-function class:set_output(filename)
-  self:info("Updating log output: " .. filename or "stdout")
-  if filename then
-    self.output = io.open(filename, "a")
-  else
-    self.output = io.output
-  end
-end
+--- Static Fields
+-- @section static-fields
+
+--- Available log levels.
+--
+-- String representations of the log levels.
+-- @table level_strings
+-- @tfield string DEBUG
+-- @tfield string INFO
+-- @tfield string WARN
+-- @tfield string ERROR
+-- @tfield string FATAL
+
+--- Available log levels.
+--
+-- Integer representations of the log levels.
+-- @table level_values
+-- @tfield integer 10
+-- @tfield integer 20
+-- @tfield integer 30
+-- @tfield integer 40
+-- @tfield integer 50
 
 class.level_strings = {"DEBUG", "INFO", "WARN", "ERROR", "FATAL"}
 class.level_values  = { 10, 20, 30, 40, 50 }
@@ -72,10 +168,32 @@ for i, _ in ipairs(class.level_strings) do
   end
 end
 
+--- Default output.
+--
+-- Output used by default by new logger instances.
+-- @tfield io.file_descriptor default_output `io.stdout`
 class.default_output = io.stdout
+--- Default log level.
+--
+-- Log level used by default by new logger instances.
+-- @tfield integer default_level_value 20
 class.default_level_value = 20
 
--- Static functions
+--- Default logger.
+--
+-- A pre-instanciated logger for quick and dirty logging.
+-- @tfield Logger main_logger
+
+--- Static Functions
+-- @section static-functions
+
+--- Standard log formatter function.
+--
+-- The default standard log formatter function, adding timestamp, message level, file and line of issuing code.
+-- @tparam Logger self The logger object
+-- @tparam string level @{level_strings|String} representation of message level
+-- @tparam string msg User log message
+-- @treturn string Logger formatted message
 function class.timestamp_output(self, level, msg)
   local result = ""
   if class.need_lf then result = result .. "\n" end
@@ -91,6 +209,9 @@ function class.timestamp_output(self, level, msg)
   return result
 end
 
+--- Set default log level.
+-- @param level Level value as @{level_values|integer} or @{level_strings|string} value.
+-- @see default_level_value
 function class.set_default_level(level)
   local int_level, str_level = class.get_levels(level)
   class.main_logger:debug("Updating default level to: " .. str_level)
@@ -98,6 +219,8 @@ function class.set_default_level(level)
   class.main_logger:set_level(int_level)
 end
 
+--- Set default output.
+-- @tparam[opt=nil] string f Name of the file to use as output or `nil` to set `io.stdout`
 function class.set_default_output(f)
   class.main_logger:info("Updating log output: " .. f or "stdout")
   if f then
@@ -108,9 +231,9 @@ function class.set_default_output(f)
 end
 
 
---- Return a string representation of a integer debug level (similar to Python ones).
--- @tparam int int_level Debug level as an integer between 0 an 50
--- @treturn string The name of the debug level suitable for lualogging
+--- Get string representation of an integer log level.
+-- @tparam integer int_level Log level as an @{level_values|integer}
+-- @treturn string The @{level_strings|string} representation of the log level
 function class._get_level_string(int_level)
   for i, v in ipairs(class.level_values) do
     if int_level <= v then
@@ -120,6 +243,9 @@ function class._get_level_string(int_level)
   return class.level_strings[1] -- Emergency case
 end
 
+--- Get integer representation of a string log level.
+-- @tparam string str_level The @{level_strings|string} representation of the log level
+-- @treturn integer Log level as an @{level_values|integer}
 function class._get_level_value(str_level)
   for i, v in ipairs(class.level_strings) do
     if str_level == v then
@@ -129,6 +255,10 @@ function class._get_level_value(str_level)
   return class.level_values[1] -- Emergency case
 end
 
+--- Get representations of the given level.
+-- @param level Log level as @{level_values|integer} or @{level_strings|string} value.
+-- @treturn integer Log level as @{level_values|integer}
+-- @treturn string Log level as @{level_strings|string}
 function class.get_levels(level)
   if type(level) == "number" then
     return level, class._get_level_string(level)
@@ -143,8 +273,6 @@ main_logger.wheel = {"|", "/", "-", "\\"}
 main_logger.wheel_step = 0
 main_logger.last_step = 0
 
---- Function to print a progressing wheel.
--- @tparam[opt] int step Step number to display
 function main_logger:progress(step)
   if class.need_lf then self.output:write("\b\b\b\b\b\b\b\b\b\b\b") end
   self.last_step = step or self.last_step
@@ -158,7 +286,6 @@ function main_logger:progress(step)
   class.need_lf = true
 end
 
---- Default logger that can be used by any module.
 class.main_logger = main_logger
 
 return module.Logger

arcades/utils/argparse.lua

---- Argument parser class
+--- Argument parser class.
+-- Declare arguments used by ARCADES.
+-- @todo Don't rely on a class declaration (just a module instead).
+-- @todo Use config file instad of complicated command line arguments.
 -- @author Alexis BRENON <alexis.brenon@imag.fr>
 -- @classmod utils.argparse.Parser
 -- @alias class
@@ -96,21 +99,22 @@ end
 
 local indent = ""
 
---- Private methods
+--- Private Methods
 -- @section private-methods
 
 --- Add elements from a table to the parser.
 --
--- There are 3 different element type, <code>text</code> which is just displayed
--- in the usage description, <code>option</code> that is the top level option
--- (it must be preceded by a hash) and <code>field</code> if it is a suboption
--- that is contained in a table.
+-- There are 3 different element type:
+--
+--   * `text` which is just displayed in the usage description;
+--   * `option` that is the top level option (it must be preceded by a dash);
+--   * `field` if it is a suboption that is contained in a table.
 --
 -- Text elements are of the form:<br/>
--- <code>{"text", "my very useful piece of text"}</code>
+-- `{"text", "my very useful piece of text"}`
 --
 -- Option and field elements are of the form:<br/>
--- <code>{"option"|"field", "option_name", default value, "Description", "type"}</code>
+-- `{"option"|"field", "option_name", default value, "Description", "type"}`
 --
 -- @tparam table elements A table representing the element.
 function class:_add_elements(elements)
@@ -141,13 +145,13 @@ function class:_add_elements(elements)
   indent = old_indent
 end
 
---- This function will parse a string in depth.
+--- Parse a string in depth.
 --
 -- Given the description of the arguments and the actual parsing result, it will
--- go deeper, casting string to the right type. This function works recurcivelly.
+-- go deeper, casting string to the right type. This function works recursivelly.
 -- @tparam table description The description of the arguments
 -- @tparam table input Result of the previous parsing
--- @treturn table <code>input</code> parsed according to the <code>description</code>
+-- @treturn table `input` parsed according to the `description`
 function class:_format(description, input)
   local output = {}
   for _, e in ipairs(description) do
@@ -195,10 +199,10 @@ function class:_format(description, input)
   return output
 end
 
---- Public methods
+--- Public Methods
 -- @section public-methods
 
---- Actually parse arg
+--- Actually parse `arg`
 -- @tparam string arg Arguments string to parse
 -- @treturn table Parsed arguments
 function class:parse(arg)

arcades/utils/ffi_cdef.lua

+--- Foreign function interface management.
+--
+-- Handle unique declaration of C functions
+-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
+
 local ffi = require('ffi') -- Lua <-> C bindings
 
 -- Do the FFI definition once
@@ -33,6 +38,16 @@ local function load_lib(alt_names)
   end
 end
 
+---Table of the `gobject` library's function
+-- @table gobject 
+
+---Table of the `cairo` library's function
+-- @table cairo 
+
+---Table of the `rsvg` library's function
+-- @table rsvg 
+
+--- @export
 return {
   gobject = load_lib({
     'gobject',

arcades/utils/init.lua

---- A set of utilities functions and classes.
+--- A set of utilities modules and classes.
 -- @package utils
 -- @author Alexis BRENON <alexis.brenon@imag.fr>