[Minor] Start of documentation for Lua API in Lua

3 files changed, 121 insertions, 0 deletions

diff --git a/lualib/lua_maps.lua b/lualib/lua_maps.lua
index 7b48db034..41ab2552c 100644
--- a/lualib/lua_maps.lua
+++ b/lualib/lua_maps.lua
@@ -1,3 +1,8 @@
+--[[[
+-- @module lua_maps
+-- This module contains helper functions for managing rspamd maps
+--]]
+
 --[[
 Copyright (c) 2017, Vsevolod Stakhov <vsevolod@highsecure.ru>
 
@@ -16,6 +21,16 @@ limitations under the License.
 
 local exports = {}
 
+--[[[
+-- @function lua_maps.map_add_from_ucl(opt, mtype, description)
+-- Creates a map from static data
+-- Returns true if map was added or nil
+-- @param {string or table} opt data for map (or URL)
+-- @param {string} mtype type of map (`set`, `map`, `radix`, `regexp`)
+-- @param {string} description human-readable description of map
+-- @return {bool} true on success, or `nil`
+--]]
+
 local function rspamd_map_add_from_ucl(opt, mtype, description)
   local ret = {
     get_key = function(t, k)
@@ -144,6 +159,17 @@ local function rspamd_map_add_from_ucl(opt, mtype, description)
   return nil
 end
 
+--[[[
+-- @function lua_maps.map_add(mname, optname, mtype, description)
+-- Creates a map from configuration elements (static data or URL)
+-- Returns true if map was added or nil
+-- @param {string} mname config section to use
+-- @param {string} optname option name to use
+-- @param {string} mtype type of map ('set', 'hash', 'radix', 'regexp')
+-- @param {string} description human-readable description of map
+-- @return {bool} true on success, or `nil`
+--]]
+
 local function rspamd_map_add(mname, optname, mtype, description)
   local opt = rspamd_config:get_module_opt(mname, optname)
 
@@ -151,7 +177,9 @@ local function rspamd_map_add(mname, optname, mtype, description)
 end
 
 exports.rspamd_map_add = rspamd_map_add
+exports.map_add = rspamd_map_add
 exports.rspamd_map_add_from_ucl = rspamd_map_add_from_ucl
+exports.map_add_from_ucl = rspamd_map_add_from_ucl
 
 -- Check `what` for being lua_map name, otherwise just compares key with what
 local function rspamd_maybe_check_map(key, what)
diff --git a/lualib/lua_redis.lua b/lualib/lua_redis.lua
index 2102db841..2fb7c3781 100644
--- a/lualib/lua_redis.lua
+++ b/lualib/lua_redis.lua
@@ -22,6 +22,11 @@ local exports = {}
 
 local E = {}
 
+--[[[
+-- @module lua_redis
+-- This module contains helper functions for working with Redis
+--]]
+
 local function try_load_redis_servers(options, rspamd_config, result)
   local default_port = 6379
   local default_timeout = 1.0
@@ -185,6 +190,20 @@ local function rspamd_parse_redis_server(module_name, module_opts, no_fallback)
   end
 end
 
+--[[[
+-- @function lua_redis.parse_redis_server(module_name, module_opts, no_fallback)
+-- Extracts Redis server settings from configuration
+-- @param {string} module_name name of module to get settings for
+-- @param {table} module_opts settings for module or `nil` to fetch them from configuration
+-- @param {boolean} no_fallback should be `true` if global settings must not be used
+-- @return {table} redis server settings
+-- @example
+-- local rconfig = lua_redis.parse_redis_server('my_module')
+-- -- rconfig contains upstream_list objects in ['write_servers'] and ['read_servers']
+-- -- ['timeout'] contains timeout in seconds
+-- -- ['expand_keys'] if true tells that redis key expansion is enabled
+--]]
+
 exports.rspamd_parse_redis_server = rspamd_parse_redis_server
 exports.parse_redis_server = rspamd_parse_redis_server
 
@@ -567,6 +586,18 @@ local function rspamd_redis_make_request(task, redis_params, key, is_write,
   return ret,conn,addr
 end
 
+--[[[
+-- @function lua_redis.redis_make_request(task, redis_params, key, is_write, callback, command, args)
+-- Sends a request to Redis
+-- @param {rspamd_task} task task object
+-- @param {table} redis_params redis configuration in format returned by lua_redis.parse_redis_server()
+-- @param {string} key key to use for sharding
+-- @param {boolean} is_write should be `true` if we are performing a write operating
+-- @param {function} callback callback function (first parameter is error if applicable, second is a 2D array (table))
+-- @param {string} command Redis command to run
+-- @param {table} args Numerically indexed table containing arguments for command
+--]]
+
 exports.rspamd_redis_make_request = rspamd_redis_make_request
 exports.redis_make_request = rspamd_redis_make_request
 
@@ -639,6 +670,12 @@ local function redis_make_request_taskless(ev_base, cfg, redis_params, key,
   return ret,conn,addr
 end
 
+--[[[
+-- @function lua_redis.redis_make_request_taskless(ev_base, redis_params, key, is_write, callback, command, args)
+-- Sends a request to Redis in context where `task` is not available for some specific use-cases
+-- Identical to redis_make_request() except in that first parameter is an `event base` object
+--]]
+
 exports.rspamd_redis_make_request_taskless = redis_make_request_taskless
 exports.redis_make_request_taskless = redis_make_request_taskless
 
diff --git a/lualib/lua_util.lua b/lualib/lua_util.lua
index f7e92937d..54b6c1d5e 100644
--- a/lualib/lua_util.lua
+++ b/lualib/lua_util.lua
@@ -14,6 +14,11 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ]]--
 
+--[[[
+-- @module lua_util
+-- This module contains utility functions for working with Lua and/or Rspamd
+--]]
+
 local exports = {}
 local lpeg = require 'lpeg'
 
@@ -32,7 +37,16 @@ local function rspamd_str_split(s, sep)
   return gr:match(s)
 end
 
+--[[[
+-- @function lua_util.str_split(text, deliminator)
+-- Splits text into a numeric table by deliminator
+-- @param {string} text deliminated text
+-- @param {string} deliminator the deliminator
+-- @return {table} numeric table containing string parts
+--]]
+
 exports.rspamd_str_split = rspamd_str_split
+exports.str_split = rspamd_str_split
 
 local space = lpeg.S' \t\n\v\f\r'
 local nospace = 1 - space
@@ -42,12 +56,32 @@ exports.rspamd_str_trim = function(s)
   return match(ptrim, s)
 end
 
+--[[[
+-- @function lua_util.round(number, decimalPlaces)
+-- Round number to fixed number of decimal points
+-- @param {number} number number to round
+-- @param {number} decimalPlaces number of decimal points
+-- @return {number} rounded number
+--]]
+
 -- Robert Jay Gould http://lua-users.org/wiki/SimpleRound
 exports.round = function(num, numDecimalPlaces)
   local mult = 10^(numDecimalPlaces or 0)
   return math.floor(num * mult) / mult
 end
 
+--[[[
+-- @function lua_util.template(text, replacements)
+-- Replaces values in a text template
+-- Variable names can contain letters, numbers and underscores, are prefixed with `$` and may or not use curly braces.
+-- @param {string} text text containing variables
+-- @param {table} replacements key/value pairs for replacements
+-- @return {string} string containing replaced values
+-- @example
+-- local goop = lua_util.template("HELLO $FOO ${BAR}!", {['FOO'] = 'LUA', ['BAR'] = 'WORLD'})
+-- -- goop contains "HELLO LUA WORLD!"
+--]]
+
 exports.template = function(tmpl, keys)
   local var_lit = lpeg.P { lpeg.R("az") + lpeg.R("AZ") + lpeg.R("09") + "_" }
   local var = lpeg.P { (lpeg.P("$") / "") * ((var_lit^1) / keys) }
@@ -160,11 +194,26 @@ exports.is_rspamc_or_controller = function(task)
   return is_rspamc
 end
 
+--[[[
+-- @function lua_util.unpack(table)
+-- Converts numeric table to varargs
+-- This is `unpack` on Lua 5.1/5.2/LuaJIT and `table.unpack` on Lua 5.3
+-- @param {table} table numerically indexed table to unpack
+-- @return {varargs} unpacked table elements
+--]]
+
 local unpack_function = table.unpack or unpack
 exports.unpack = function(t)
   return unpack_function(t)
 end
 
+--[[[
+-- @function lua_util.spairs(table)
+-- Like `pairs` but keys are sorted lexicographically
+-- @param {table} table table containing key/value pairs
+-- @return {function} generator function returning key/value pairs
+--]]
+
 -- Sorted iteration:
 -- for k,v in spairs(t) do ... end
 --
@@ -199,6 +248,13 @@ end
 
 exports.spairs = spairs
 
+--[[[
+-- @function lua_util.disable_module(modname, how)
+-- Disables a plugin or disables redis for a plugin.
+-- @param {string} modname name of plugin to disable
+-- @param {string} how 'redis' to disable redis, 'config' to disable startup
+--]]
+
 local function disable_module(modname, how)
   if rspamd_plugins_state.enabled[modname] then
     rspamd_plugins_state.enabled[modname] = nil