write code documentation

init.lua

@@ -3,6 +3,16 @@ local syspath = modpath..'system'..DIR_DELIM
 local S = minetest.get_translator('mtimer')
 
 
+-- Set initial global `mtimer` table
+--
+-- The sub-table `show_formspec` is filled programmatically and is used for the
+-- functions that show the formspecs to the player.
+--
+-- In sub-table `meta` the meta keys and their default values are defined. Those
+-- are iterated over when a player joins. The names are searched for whenever
+-- somewhere in the code a meta information is to be loaded.
+--
+-- @see ./system/formspec/formspec_creation.lua
 mtimer = {
     translator = S,
     show_formspec = {},
@@ -45,6 +55,7 @@ dofile(syspath..'formspec'..DIR_DELIM..'formspec_helpers.lua')
 dofile(syspath..'formspec'..DIR_DELIM..'real_time_universal.lua')
 dofile(syspath..'formspec'..DIR_DELIM..'formspec_creation.lua')
 
+
 -- Load system
 dofile(syspath..'chat_command.lua')
 dofile(syspath..'update_timer.lua')
@@ -53,4 +64,3 @@ dofile(syspath..'on_joinplayer.lua')
 dofile(syspath..'get_times.lua')
 dofile(syspath..'get_timer_data.lua')
 dofile(syspath..'register_globalstep.lua')
-

system/chat_command.lua

@@ -4,10 +4,40 @@ local fs = m.show_formspec
 local cs = minetest.chat_send_player
 
 
+-- Colorize a command sequence
+--
+-- This function returns a colorized chat command sequence with the given
+-- parameter and the needed spacing
+--
+-- @param command The chat command paramter
+-- @return table  The colorized string
 local command = function (command)
      return minetest.colorize('cyan', '/mtimer '..command..'   ')
 end
 
+
+-- Chat command
+--
+-- The `/mtimer` chat command opens the main menu and allows to directly open
+-- the formspecs for the specific configuration. It can be run by all users.
+--
+-- The following parameters are supported.
+--
+--  Parameter   Mnemonic           Action
+-- -------------------------------------------------------------------
+--  vi          visibility         fs.set_visibility(name)
+--  po          position           fs.set_position(name)
+--  co          color              fs.sec_color(name)
+--  tz          timezone           fs.timezone_offset(name)
+--  in          ingame             fs.ingame_time_format(name)
+--  re          real               fs.real_world_time_format(name)
+--  st          start time         fs.session_start_time_format(name)
+--  sd          session duration   fs.session_duration_format(name)
+--  tf          timer format       fs.timer_format(name)
+-- -------------------------------------------------------------------
+--  help        Prints the help output showing the parameters
+--
+-- Providing unknown parameters has no effect.
 minetest.register_chatcommand('mtimer', {
     description = S('Configure timer display'),
     params = '<vi/po/co/tz/in/re/st/sd/tt/help>',
@@ -29,9 +59,9 @@ minetest.register_chatcommand('mtimer', {
 
         if action == 'help' then
             local message = {
-                command('vi')..S('Set Visibility'),
-                command('po')..S('Set Position'),
-                command('co')..S('Set Color'),
+                command('vi')..S('Visibility'),
+                command('po')..S('Position'),
+                command('co')..S('Color'),
                 command('tz')..S('Timezone Offset'),
                 command('in')..S('Ingame Time Format'),
                 command('re')..S('Real-World Time Format'),

system/formspec/formspec_creation.lua

@@ -4,6 +4,17 @@ local build_frame = m.build_frame
 local fe = minetest.formspec_escape
 
 
+-- Formspecs are loaded and shown by individual functions. The function name
+-- correlates with the formspec to show. All of the names are self-explanatory
+-- and within the functions no logic is used.
+--
+-- @see mtimer.build_frame
+-- @see mtimer.get_times
+-- @see ./system/on_receive_fields.lua
+-- @see ./system/chat_command.lua
+-- @see https://dev.minetest.net/formspec
+
+
 mtimer.show_formspec.main_menu = function (player_name)
     minetest.show_formspec(player_name, 'mtimer:main_menu', [[
     size[9.5,6]

system/formspec/formspec_helpers.lua

@@ -2,6 +2,19 @@ local m = mtimer
 local S = m.translator
 
 
+-- Build the formspec frame
+--
+-- With this function the size and title of  a formspec are set. It also adds
+-- the default buttons to the formspec. All calculations for the buttons are
+-- done automatically but directly correlate to the size of the formspec.
+--
+-- All formspecs are by minimum 6 units wide and 2 units high to allow enough
+-- space for the buttons and the button texts.
+--
+-- @param width  The width of the formspec in formspec units
+-- @param height The height of the formspec in formspec units
+-- @param title  The title for the formspec (a label shown on the formspec)
+-- @return string the constructed “frame”
 mtimer.build_frame = function (width, height, title)
     local formspec_frame = [[
     size[+width,+height] label[0,-0.125;+title]

system/formspec/real_time_universal.lua

@@ -4,6 +4,17 @@ local build_frame = m.build_frame
 local fe = minetest.formspec_escape
 
 
+-- Real Time Universal Formspec
+--
+-- This formspec can be used to show formatting options for all real-world time
+-- values that can be formatted within mTimer. Since all the real-world times
+-- are defined identically this formspec exists so it has to be defined only
+-- once and can be re-used as needed.
+--
+-- @param player_name The name of the player to show the formspec to
+-- @config time_type  A time type that is provided by the `get_times` function
+-- @return void
+-- @see mtimer.get_times
 mtimer.show_formspec.real_time_universal = function (player_name, config)
     local time_data = mtimer.get_times(player_name)[config.time_type]
 

system/get_timer_data.lua

@@ -1,7 +1,18 @@
 local m = mtimer
 local S = m.translator
 
-
+-- Get parsed timer data
+--
+-- Returns the parsed timer data (i.e. all variables are replaced with their
+-- respective values) for the given player referenced by the name.
+--
+-- The returned table holds the formatted version as well as the individual
+-- times (session start, current date, etc.) as configured via the respective
+-- dialogs. This will be used for the Timer itself as well as in the
+-- configuration formspec.
+--
+-- @param player_name The name of the player to get the timer data for
+-- @return table The timer data of the player
 mtimer.get_timer_data = function (player_name)
     local player_meta = minetest.get_player_by_name(player_name):get_meta()
     local time_data = mtimer.get_times(player_name)

system/get_times.lua

@@ -2,6 +2,15 @@ local m = mtimer
 local S = m.translator
 
 
+-- Get translated date names
+--
+-- This helper function takes a table containing a numerical month and a
+-- numerical day of the week and returns the respecive names.
+--
+--   { day = 1, month = 6 }   ->   { day = S('Monday'), month = S('May') }
+--
+-- @param dates A table of dates as described
+-- @return table The table containing the date names
 local get_date_names = function (dates)
     -- %w -> weekday [0-6 = Sunday-Saturday]
     local weekdays = {
@@ -21,6 +30,43 @@ local get_date_names = function (dates)
 end
 
 
+-- Real-world time handling
+--
+-- This function returns the formatted string as well a s the raw format string
+-- and all the replacement values for the variables basing on what time type
+-- was requested. The types are `real` for the real-world time or `session`
+-- for the session start time.
+--
+-- Both of the times use the same syntax and have the same variables to set so
+-- one function is used for both when getting the times with `mtimer.get_times`
+-- where needed.
+--
+--   {
+--     times = {
+--       server_time = ISO 8601 date of the server’s timestamp,
+--       server_local = ISO 8601 date of the local ofsetted timestamp,
+--       offset = timezone offset as set by the player
+--     },
+--     variables = {
+--       hours_24 = 24h representation of the time,
+--       hours_12 = 12h representation of the time,
+--       minutes = minutes for the requested time,
+--       seconds = seconds for the requested time,
+--       dayname = name of the day for the requested time,
+--       monthname = name of the month for the requested time,
+--       year = year of the requested time,
+--       month = month of the requested time,
+--       day = day of the requested time,
+--       iso8601_date = ISO 8601 date part based on the requested time,
+--       iso8601_time = ISO 8601 time part based on the requested time
+--     },
+--     format = raw string for formatting the requeste time type,
+--     formatted = the formatted (all variables replaced) string
+--   }
+--
+-- @param player_name The name of the player to get the times for
+-- @param time_type   A Time type as described
+-- @return table      The table containing the data as described
 local get_real_time_universal = function (player_name, time_type)
     local player = minetest.get_player_by_name(player_name)
     local player_meta = player:get_meta()
@@ -87,6 +133,32 @@ local get_real_time_universal = function (player_name, time_type)
 end
 
 
+-- Getting the ingame time
+--
+-- This function gets and parses the ingame time based on the configuration set
+-- by the player. The following table is returned.
+--
+-- {
+--   hours_24 =  24h representation of the time,
+--   hours_12 = 12h representation of the time,
+--   minutes = minutes for the requested time,
+--   ingame_timestamp = timestamp of the ingame time (seconds since 0),
+--   format = raw string for formatting the time,
+--   formatted = the formatted (all variables replaced) string
+-- }
+--
+-- Calculation: The function `minetest.get_timeofday()` returns a fraction
+--              between 0 and 1 for the time of the day. Multiplication with
+--              24000 converts this number to a millihours value (mh). By
+--              multiplication with 3.6 the mh value is converted into a
+--              seconds value that can be used as timestamp.
+--
+-- Usabiliy: After 86400 seconds (or 24000 mh) the timestamp returns to 0 and
+--           thus is only useful to represent the time of the day and nothing
+--           else like the date or something like that.
+--
+-- @param player_name The name of the player to get the time for
+-- @return table The table as described
 local get_ingame_time = function (player_name)
     local player = minetest.get_player_by_name(player_name)
     local format = player:get_meta():get_string(m.meta.ingame_time.key)
@@ -112,6 +184,25 @@ local get_ingame_time = function (player_name)
 end
 
 
+-- Getting the session duration
+--
+-- This function gets the session start timestamp and the current timestamp and
+-- calculates the difference in days, hours, minutes, and seconds. The values
+-- are added to the return table as shown below. Additionaly the format string
+-- and the formatted result string are added to this table
+--
+-- {
+--   format = raw string for formatting the time,
+--   difference = the raw difference in seconds,
+--   days = days the difference is long,
+--   hours = hours the difference is long,
+--   minutes = minutes the difference is long,
+--   seconds = seconds the difference is long,
+--   formatted = the formatted (all variables replaced) string
+-- }
+--
+-- @param player_name The name of the player to get the duration for
+-- @return table The table as described
 local get_session_duration = function (player_name)
     local player = minetest.get_player_by_name(player_name)
     local player_meta = player:get_meta()
@@ -140,6 +231,20 @@ local get_session_duration = function (player_name)
 end
 
 
+-- Get the times
+--
+-- Returns the times for the given player referenced by the player’s name as
+-- a table as shown below.
+--
+-- {
+--   session_start_time = @see get_real_time_universal,
+--   session_duration = @see get_session_duration,
+--   real_time = @see get_real_time_universal,
+--   ingame_time = @see get_ingame_time
+-- }
+--
+-- @param player_name The name of the player to get the times for
+-- @return table The table containing the times as described
 mtimer.get_times = function (player_name)
     return {
         session_start_time = get_real_time_universal(player_name, 'session'),

system/on_joinplayer.lua

@@ -1,5 +1,11 @@
 local m = mtimer
 
+
+-- When a player joins
+--
+-- 1. Set default values if not set
+-- 2. Set session start timestamp
+-- 3. Set “empty” HUD element and write ID to meta data for later use
 minetest.register_on_joinplayer(function(player)
     local meta = player:get_meta()
 

system/on_receive_fields.lua

@@ -1,6 +1,11 @@
 local m = mtimer
 local f = mtimer.show_formspec
 
+
+-- When formspec data is sent to the server check for the formname and run the
+-- specific action for the given form. See Individual descriptions. The code
+-- for this is very simple because most of the logic is handled in the
+-- timer functions and not in the formspec code.
 minetest.register_on_player_receive_fields(function(player, formname, fields)
     local meta = player:get_meta()
     local name = player:get_player_name()
@@ -142,4 +147,5 @@ minetest.register_on_player_receive_fields(function(player, formname, fields)
         end
     end
 
+
 end)

system/register_globalstep.lua

@@ -1,13 +1,18 @@
 local m = mtimer
+local update_timer = m.update_timer
 local connected_players = minetest.get_connected_players
 local timer = 0
 
+
+-- The globalstep iterates over all players every second and updates the timers
+-- by invoking the `mtimer.update_timer` function that has ben localized to
+-- `update_timer` for faster access.
 minetest.register_globalstep(function(dtime)
     timer = timer + dtime;
     if timer < 1 then return end
 
     for _,player in pairs(connected_players()) do
-        m.update_timer(player:get_player_name())
+        update_timer(player:get_player_name())
     end
 
     timer = 0

system/update_timer.lua

@@ -1,6 +1,27 @@
 local m = mtimer
 
-
+-- Calculate HUD positions and offsets
+--
+-- Based on the given named position a table of positional tables is returned
+-- by this helper function. When an invalid named position is provided all
+-- tables only contain 0 values. Valid positions shown in the diagram below.
+--
+--   +--------------------------------+
+--   | tl            tc            tr |
+--   |                                |
+--   |                                |
+--   | ml            mc            mr |
+--   |                                |
+--   |                                |
+--   | bl            bc            br |
+--   +--------------------------------+
+--
+-- For orientation: `mc` is the center of the screen (where the crosshair is).
+--                  `bc` is the location of the hotbar and health bars, etc.
+--                  Both are valid positions but should not be used.
+--
+-- @param pos A positional string as described
+-- @return table a Table containing the positional tables based on the string
 local get_hud_positions = function (pos)
     local p = { x = 0, y = 0 }
     local a = { x = 0, y = 0 }
@@ -20,6 +41,17 @@ local get_hud_positions = function (pos)
 end
 
 
+-- Update the timer
+--
+-- This function updates the timer for the given player referenced by the
+-- player’s name. The function is called when a formspec update (fields) is
+-- sent to the server and is automatically called by the registered globalstep.
+--
+-- The function sets the needed values based on the player meta data and uses
+-- the `mtimer.get_timer_data` function for the actual data to be shown.
+--
+-- @param player_name Name of the player to update the timer for
+-- @return void
 mtimer.update_timer = function (player_name)
     local player = minetest.get_player_by_name(player_name)
     local meta = player:get_meta()