From: Vsevolod Stakhov <vsevolod@highsecure.ru>
Date: Thu, 9 Apr 2015 17:41:19 +0000 (+0100)
Subject: Add documentation for lua logger.
X-Git-Tag: 0.9.0~269
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=80b34ec2ba9976341aa2087d98261066f1ca7314;p=rspamd.git

Add documentation for lua logger.
---

diff --git a/doc/Makefile b/doc/Makefile
index ef7b29081..be09d42ce 100644
--- 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 eff7df3fe..dbeea2ea3 100644
--- 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 a384e36cc..b477d3f9b 100644
--- 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"
  *