commit 47e1e81: [Minor] Add documentation for lua cdb module

[Vsevolod Stakhov]

Author: Vsevolod Stakhov
Date: 2021-10-19 20:51:30 +0100
URL: https://github.com/rspamd/rspamd/commit/47e1e81710bd9388de4c80e4b326735f86e4c831 (HEAD -> master)

[Minor] Add documentation for lua cdb module

---
 doc/Makefile      |  7 +++++--
 src/lua/lua_cdb.c | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index 548c6b292..53ed9b6cc 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -21,7 +21,8 @@ lua-dirs:
 lua-doc: lua-dirs rspamd_regexp rspamd_ip rspamd_config rspamd_task ucl rspamd_http rspamd_trie \
 	rspamd_resolver rspamd_redis rspamd_upstream_list rspamd_expression rspamd_mimepart rspamd_logger rspamd_url \
 	rspamd_tcp rspamd_mempool rspamd_html rspamd_util rspamd_sqlite3 rspamd_cryptobox rspamd_map \
-	lua_redis lua_util lua_maps lua_clickhouse lua_selectors rspamd_udp rspamd_text lua_mime rspamd_parsers
+	lua_redis lua_util lua_maps lua_clickhouse lua_selectors rspamd_udp rspamd_text lua_mime rspamd_parsers \
+	rspamd_cdb
 
 lua_redis:
 	$(LLUADOC) < ../lualib/lua_redis.lua > markdown/lua/lua_redis.md
@@ -88,4 +89,6 @@ rspamd_udp: ../src/lua/lua_udp.c
 rspamd_text: ../src/lua/lua_text.c
 	$(LUADOC) < ../src/lua/lua_text.c > markdown/lua/rspamd_text.md
 rspamd_parsers: ../src/lua/lua_parsers.c
-	$(LUADOC) < ../src/lua/lua_parsers.c > markdown/lua/rspamd_parsers.md
\ No newline at end of file
+	$(LUADOC) < ../src/lua/lua_parsers.c > markdown/lua/rspamd_parsers.md
+rspamd_cdb: ../src/lua/lua_cdb.c
+	$(LUADOC) < ../src/lua/lua_cdb.c > markdown/lua/rspamd_cdb.md
\ No newline at end of file
diff --git a/src/lua/lua_cdb.c b/src/lua/lua_cdb.c
index 37f35d985..e0b9d9439 100644
--- a/src/lua/lua_cdb.c
+++ b/src/lua/lua_cdb.c
@@ -18,13 +18,65 @@
 
 #define CDB_REFRESH_TIME 60
 
+/***
+ * @module rspamd_cdb
+ * Rspamd CDB module is used to read and write key/value pairs to the CDB file
+ *
+ * @example
+local rspamd_cdb = require "rspamd_cdb"
+rspamd_cdb.build('/tmp/test.cdb'):add('test', 'value'):finalize()
+local c = rspamd_cdb.open('/tmp/test.cdb')
+c:find('test')
+-- will return 'value'
+ */
+
+/***
+ * @function rspamd_cdb.open(filename, [ev_base])
+ * Opens an existing CDB for reading. If `ev_base` is specified, then cdb file is added
+ * for monitoring, that will get updates on disk file changes.
+ * @param {string} filename path to file
+ * @param {ev_base} event loop object
+ * @return {rspamd_cdb} cdb object
+ */
 LUA_FUNCTION_DEF (cdb, create);
+/***
+ * @method rspamd_cdb:find(key)
+ * Finds a specific key in cdb and returns a string or nil if a key has not been found
+ * @param {string} key key to find
+ * @return {string/nil} value for the specific key
+ */
 LUA_FUNCTION_DEF (cdb, lookup);
+/***
+ * @method rspamd_cdb:get_name()
+ * Returns filename for the specific cdb
+ * @return {string} filename for cdb
+ */
 LUA_FUNCTION_DEF (cdb, get_name);
 LUA_FUNCTION_DEF (cdb, destroy);
 
+/***
+ * @function rspamd_cdb.build(filename, [mode])
+ * Creates a new cdb in a file (existing one will be overwritten!). The object
+ * returned can be used merely for adding data. Upon finalizing, the data is written to
+ * disk and cdb can no longer be changed.
+ * @param {string} filename path to file
+ * @param {int} mode numeric mode to create a file
+ * @return {rspamd_cdb_builder} cdb builder object (or nil + error message)
+ */
 LUA_FUNCTION_DEF (cdb, build);
+/***
+ * @method rspamd_cdb_builder:add(key, value)
+ * Adds new value to cdb in the builder mode
+ * @param {string} key key to add
+ * @param {string} value value to associate with the key
+ * @return {rspamd_cdb_builder} the same object to allow chaining calls
+ */
 LUA_FUNCTION_DEF (cdb_builder, add);
+/***
+ * @method rspamd_cdb_builder:finalize()
+ * Finalizes the CDB and writes it to disk. This method also closes FD associated with
+ * CDB builder. No further additions are allowed after this point
+ */
 LUA_FUNCTION_DEF (cdb_builder, finalize);
 LUA_FUNCTION_DEF (cdb_builder, dtor);