From: Donald Lee <dlqs@gmx.com>
Date: Thu, 24 Jun 2021 16:05:37 +0000 (+0800)
Subject: lib: add comments for functions
X-Git-Tag: base_8.1~355^2~4
X-Git-Url: https://git.puffer.fish/?a=commitdiff_plain;h=19eee398d4f25af835837894b276e2a1796a98f5;p=matthieu%2Ffrr.git

lib: add comments for functions

Signed-off-by: Donald Lee <dlqs@gmx.com>
---

diff --git a/lib/compiler.h b/lib/compiler.h
index 155ffc6003..a6fd858518 100644
--- a/lib/compiler.h
+++ b/lib/compiler.h
@@ -174,11 +174,10 @@ extern "C" {
 	MACRO_VARIANT(_MACRO_REPEAT, ##__VA_ARGS__)(NAME, ##__VA_ARGS__)
 
 /* per-arglist repeat macro, use like this:
- * #define SEP_SEMICOLON   ;
- * #define foo(...) MAP_LISTS(F, SEP_SEMICOLON, ##__VA_ARGS__)
+ * #define foo(...) MAP_LISTS(F, ##__VA_ARGS__)
  * where F is a n-ary function where n is the number of args in each arglist.
- * e.g.: MAP_LISTS(f, SEP_SEMICOLON, (a, b), (c, d, e))
- * expands to: f(a, b); f(c, d, e)
+ * e.g.: MAP_LISTS(f, (a, b), (c, d))
+ * expands to: f(a, b); f(c, d)
  */
 
 #define ESC(...) __VA_ARGS__
@@ -196,6 +195,7 @@ extern "C" {
 	ESC(M _1; M _2; M _3; M _4; M _5; M _6; M _7)
 #define _MAP_LISTS_8(M, _1, _2, _3, _4, _5, _6, _7, _8)                        \
 	ESC(M _1; M _2; M _3; M _4; M _5; M _6; M _7; M _8)
+
 /*
  * for warnings on macros, put in the macro content like this:
  *   #define MACRO BLA CPP_WARN("MACRO has been deprecated")
diff --git a/lib/frrlua.c b/lib/frrlua.c
index 36f1797473..e97e48121c 100644
--- a/lib/frrlua.c
+++ b/lib/frrlua.c
@@ -52,10 +52,9 @@ int frrlua_table_get_integer(lua_State *L, const char *key)
 }
 
 /*
- * Encoders.
- *
  * This section has functions that convert internal FRR datatypes into Lua
- * datatypes.
+ * datatypes: one encoder function and two decoder functions for each type.
+ *
  */
 
 void lua_pushprefix(lua_State *L, const struct prefix *prefix)
@@ -303,6 +302,9 @@ void *lua_tostringp(lua_State *L, int idx)
 	return string;
 }
 
+/*
+ * Decoder for const values, since we cannot modify them.
+ */
 void lua_decode_noop(lua_State *L, int idx, const void *ptr)
 {
 }
diff --git a/lib/frrscript.h b/lib/frrscript.h
index 502921539a..8612c602f3 100644
--- a/lib/frrscript.h
+++ b/lib/frrscript.h
@@ -109,6 +109,15 @@ void frrscript_init(const char *scriptdir);
 		DECODE_ARGS_WITH_STATE(L, value);                              \
 	} while (0)
 
+/*
+ * Maps the type of value to its encoder/decoder.
+ * Add new mappings here.
+ *
+ * L
+ *    Lua state
+ * scriptdir
+ *    Directory in which to look for scripts
+ */
 #define ENCODE_ARGS_WITH_STATE(L, value)                                       \
 	_Generic((value), \
 long long * : lua_pushintegerp,                                 \
@@ -145,14 +154,21 @@ const struct prefix * : lua_decode_noop                         \
  * fs
  *    The script to call; this is obtained from frrscript_load().
  *
- * env
- *    The script's environment. Specify this as an array of frrscript_env.
- *
  * Returns:
  *    0 if the script ran successfully, nonzero otherwise.
  */
 int _frrscript_call(struct frrscript *fs);
 
+/*
+ * Wrapper for call script. Maps values passed in to their encoder
+ * and decoder types.
+ *
+ * fs
+ *    The script to call; this is obtained from frrscript_load().
+ *
+ * Returns:
+ *    0 if the script ran successfully, nonzero otherwise.
+ */
 #define frrscript_call(fs, ...)                                                \
 	({                                                                     \
 		lua_State *L = fs->L;                                          \