Add documentation for lua logger.

diff --git a/doc/Makefile b/doc/Makefile
index ef7b29081c75aac3169c7f061fb3789e8331fd71..be09d42ce0294435956f0469b05149e194912c58 100644 (file)
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -13,7 +13,7 @@ rspamc.1: rspamc.1.md
        $(PANDOC) -s -f markdown -t man -o rspamc.1 rspamc.1.md 
        
 lua-doc: lua_regexp lua_ip lua_config lua_task lua_ucl lua_http lua_trie \
-       lua_dns lua_redis lua_upstream lua_expression lua_mimepart
+       lua_dns lua_redis lua_upstream lua_expression lua_mimepart lua_logger
 
 lua_regexp: ../src/lua/lua_regexp.c
        $(LUADOC) < ../src/lua/lua_regexp.c > markdown/lua/regexp.md
@@ -38,4 +38,6 @@ lua_upstream: ../src/lua/lua_upstream.c
 lua_expression: ../src/lua/lua_expression.c
        $(LUADOC) < ../src/lua/lua_expression.c > markdown/lua/expression.md
 lua_mimepart: ../src/lua/lua_mimepart.c
-       $(LUADOC) < ../src/lua/lua_mimepart.c > markdown/lua/mimepart.md
\ No newline at end of file
+       $(LUADOC) < ../src/lua/lua_mimepart.c > markdown/lua/mimepart.md
+lua_logger: ../src/lua/lua_logger.c
+       $(LUADOC) < ../src/lua/lua_logger.c > markdown/lua/logger.md
\ No newline at end of file

diff --git a/src/lua/lua_logger.c b/src/lua/lua_logger.c
index eff7df3fee96d7ec8743599e28f81dbd64822732..dbeea2ea3a2c96ebc1e6e22aa6f6e3a7815b302e 100644 (file)
--- a/src/lua/lua_logger.c
+++ b/src/lua/lua_logger.c
@@ -25,17 +25,104 @@
 
 #include "lua_common.h"
 
+/***
+ * @module rspamd_logger
+ * Rspamd logger module is used to log messages from LUA API to the main rspamd logger.
+ * It supports legacy and modern interfaces allowing highly customized an convenient log functions.
+ * Here is an example of logger usage:
+ * @example
+local rspamd_logger = require "rspamd_logger"
+
+local a = 'string'
+local b = 1.5
+local c = 1
+local d = {
+       'aa',
+       1,
+       'bb'
+}
+local e = {
+       key = 'value',
+       key2 = 1.0
+}
+
+-- New extended interface
+
+rspamd_logger.infox('a=%1, b=%2, c=%3, d=%4, e=%5', a, b, c, d, e)
+-- Output: a=string, b=1.50000, c=1, d={[1] = aa, [2] = 1, [3] = bb} e={[key]=value, [key2]=1.0}
+
+-- Legacy interface (can handle merely strings)
+rspamd_logger.info('Old stupid API')
+
+-- Create string using logger API
+local str = rspamd_logger.slog('a=%1, b=%2, c=%3, d=%4, e=%5', a, b, c, d, e)
+
+print(str)
+-- Output: a=string, b=1.50000, c=1, d={[1] = aa, [2] = 1, [3] = bb} e={[key]=value, [key2]=1.0}
+ */
+
 static gsize lua_logger_out_type (lua_State *L, gint pos, gchar *outbuf, gsize len);
 
 /* Logger methods */
+/***
+ * @function logger.err(msg)
+ * Log message as an error
+ * @param {string} msg string to be logged
+ */
 LUA_FUNCTION_DEF (logger, err);
+/***
+ * @function logger.warn(msg)
+ * Log message as a warning
+ * @param {string} msg string to be logged
+ */
 LUA_FUNCTION_DEF (logger, warn);
+/***
+ * @function logger.info(msg)
+ * Log message as an informational message
+ * @param {string} msg string to be logged
+ */
 LUA_FUNCTION_DEF (logger, info);
+/***
+ * @function logger.debug(msg)
+ * Log message as a debug message
+ * @param {string} msg string to be logged
+ */
 LUA_FUNCTION_DEF (logger, debug);
+/***
+ * @function logger.errx(fmt[, args)
+ * Extended interface to make an error log message
+ * @param {string} fmt format string, arguments are encoded as %<number>
+ * @param {any} args list of arguments to be replaced in %<number> positions
+ */
 LUA_FUNCTION_DEF (logger, errx);
+/***
+ * @function logger.warn(fmt[, args)
+ * Extended interface to make a warning log message
+ * @param {string} fmt format string, arguments are encoded as %<number>
+ * @param {any} args list of arguments to be replaced in %<number> positions
+ */
 LUA_FUNCTION_DEF (logger, warnx);
+/***
+ * @function logger.infox(fmt[, args)
+ * Extended interface to make an informational log message
+ * @param {string} fmt format string, arguments are encoded as %<number>
+ * @param {any} args list of arguments to be replaced in %<number> positions
+ */
 LUA_FUNCTION_DEF (logger, infox);
+/***
+ * @function logger.debugx(fmt[, args)
+ * Extended interface to make a debug log message
+ * @param {string} fmt format string, arguments are encoded as %<number>
+ * @param {any} args list of arguments to be replaced in %<number> positions
+ */
 LUA_FUNCTION_DEF (logger, debugx);
+/***
+ * @function logger.slog(fmt[, args)
+ * Create string replacing percent params with corresponding arguments
+ * @param {string} fmt format string, arguments are encoded as %<number>
+ * @param {any} args list of arguments to be replaced in %<number> positions
+ * @return {string} string with percent parameters substituted
+ */
 LUA_FUNCTION_DEF (logger, slog);
 
 static const struct luaL_reg loggerlib_f[] = {

diff --git a/src/lua/lua_regexp.c b/src/lua/lua_regexp.c
index a384e36cc8cb4995dfc7e7d6e66ac3d4986d7dab..b477d3f9ba08a15a41d5ff13c8621f076721c125 100644 (file)
--- a/src/lua/lua_regexp.c
+++ b/src/lua/lua_regexp.c
@@ -25,9 +25,9 @@
 #include "regexp.h"
 
 /***
+ * @module rspamd_regexp
  * Rspamd regexp is an utility module that handles rspamd perl compatible
  * regular expressions
- * @module rspamd_regexp
  * @example
  * local rspamd_regexp = require "rspamd_regexp"
  *