ctrl: Add doxygen API documentation; generate html from it

Closes: OS#3293
Change-Id: I8dc2f24d4bf557ff7bb0f2f46881f9f8d9d7f86f

1 files changed, 77 insertions, 6 deletions

diff --git a/include/osmocom/ctrl/control_cmd.h b/include/osmocom/ctrl/control_cmd.h
index a5df753d..08376f3c 100644
--- a/include/osmocom/ctrl/control_cmd.h
+++ b/include/osmocom/ctrl/control_cmd.h
@@ -15,6 +15,7 @@
 
 struct ctrl_handle;
 
+/*! The class of node at which a ctrl command is registered to */
 enum ctrl_node_type {
 	CTRL_NODE_ROOT,	/* Root elements */
 	CTRL_NODE_BTS,	/* BTS specific (net.btsN.) */
@@ -25,6 +26,7 @@ enum ctrl_node_type {
 	_LAST_CTRL_NODE
 };
 
+/*! Ctrl command types (GET, SET, ...) */
 enum ctrl_type {
 	CTRL_TYPE_UNKNOWN,
 	CTRL_TYPE_GET,
@@ -35,37 +37,47 @@ enum ctrl_type {
 	CTRL_TYPE_ERROR
 };
 
+/*! human-readable string names for \ref ctrl_type */
 extern const struct value_string ctrl_type_vals[];
 
+/*! Represents a single ctrl connection */
 struct ctrl_connection {
 	struct llist_head list_entry;
 
-	/* The queue for sending data back */
+	/*! The queue for sending data back */
 	struct osmo_wqueue write_queue;
 
-	/* Buffer for partial input data */
+	/*! Buffer for partial input data */
 	struct msgb *pending_msg;
 
-	/* Callback if the connection was closed */
+	/*! Callback if the connection was closed */
 	void (*closed_cb)(struct ctrl_connection *conn);
 
-	/* Pending commands for this connection */
+	/*! Pending commands for this connection */
 	struct llist_head cmds;
 
-	/* Pending deferred commands for this connection */
+	/*! Pending deferred command responses for this connection */
 	struct llist_head def_cmds;
 };
 
 struct ctrl_cmd_def;
 
+/*! Represents a single ctrl command after parsing */
 struct ctrl_cmd {
+	/*! connection through which the command was received */
 	struct ctrl_connection *ccon;
+	/*! command type */
 	enum ctrl_type type;
 	char *id;
+	/*! node of the specified variable */
 	void *node;
+	/*! name of the variable */
 	char *variable;
+	/*! value of the specified CTRL variable */
 	char *value;
+	/*! respnse message string */
 	char *reply;
+	/*! state representing deferred (async) response, if any */
 	struct ctrl_cmd_def *defer;
 };
 
@@ -77,11 +89,17 @@ struct ctrl_cmd_struct {
 	char **command;
 };
 
+/*! Implementation of a given CTRL command. This is what a program registers
+ *  using \r ctrl_cmd_install in order to implement a given control variable. */
 struct ctrl_cmd_element {
+	/*! textual name/id of the CTRL command */
 	const char *name;
 	struct ctrl_cmd_struct strcmd;
+	/*! call-back function implementing the SET operation */
 	int (*set)(struct ctrl_cmd *cmd, void *data);
+	/*! call-back function implementing the GET operation */
 	int (*get)(struct ctrl_cmd *cmd, void *data);
+	/*! call-back function to validate a value; called before SET */
 	int (*verify)(struct ctrl_cmd *cmd, const char *value, void *data);
 };
 
@@ -113,6 +131,10 @@ struct ctrl_cmd *ctrl_cmd_cpy(void *ctx, struct ctrl_cmd *cmd);
 struct ctrl_cmd *ctrl_cmd_create(void *ctx, enum ctrl_type);
 struct ctrl_cmd *ctrl_cmd_trap(struct ctrl_cmd *cmd);
 
+/*! Helper to generate static struct ctrl_cmd_element
+ *  \param[in] cmdname symbol name of the command related functions/structures
+ *  \param[in] cmdstr string name exposed on CTRL
+ *  \param[in] verify_name full symbol name of verification function */
 #define CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_name) \
 static struct ctrl_cmd_element cmd_##cmdname = { \
 	.name = cmdstr, \
@@ -121,6 +143,10 @@ static struct ctrl_cmd_element cmd_##cmdname = { \
 	.verify = verify_name, \
 }
 
+/*! Helper to generate static GET function for integer
+ *  \param[in] cmdname symbol name of the command related function
+ *  \param[in] dtype name of outer struct of user data
+ *  \param[in] element name of field within \a dtype */
 #define CTRL_HELPER_GET_INT(cmdname, dtype, element) \
 static int get_##cmdname(struct ctrl_cmd *cmd, void *_data) \
 { \
@@ -132,6 +158,11 @@ static int get_##cmdname(struct ctrl_cmd *cmd, void *_data) \
 	} \
 	return CTRL_CMD_REPLY; \
 }
+
+/*! Helper to generate static SET function for integer
+ *  \param[in] cmdname symbol name of the command related function
+ *  \param[in] dtype name of outer struct of user data
+ *  \param[in] element name of field within \a dtype */
 #define CTRL_HELPER_SET_INT(cmdname, dtype, element) \
 static int set_##cmdname(struct ctrl_cmd *cmd, void *_data) \
 { \
@@ -140,6 +171,11 @@ static int set_##cmdname(struct ctrl_cmd *cmd, void *_data) \
 	node->element = tmp; \
 	return get_##cmdname(cmd, _data); \
 }
+
+/*! Helper to generate static VERIFY unction validating a numeric range
+ *  \param[in] cmdname symbol name of the command related function
+ *  \param[in] min minimum permitted integer value
+ *  \param[in] max maximum permitted integer value */
 #define CTRL_HELPER_VERIFY_RANGE(cmdname, min, max) \
 static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *_data) \
 { \
@@ -151,12 +187,23 @@ static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *_data
 	return -1; \
 }
 
+/*! Helper to generate GET, SET, VERIFY + ctrl_cmd_element for integer
+ *  \param[in] cmdname symbol name of the command related function
+ *  \param[in] cmdstr string name exposed on CTRL
+ *  \param[in] dtype name of outer struct of user data
+ *  \param[in] element name of field within \a dtype
+ *  \param[in] min minimum permitted integer value
+ *  \param[in] max maximum permitted integer value */
 #define CTRL_CMD_DEFINE_RANGE(cmdname, cmdstr, dtype, element, min, max) \
 	CTRL_HELPER_GET_INT(cmdname, dtype, element) \
 	CTRL_HELPER_SET_INT(cmdname, dtype, element) \
 	CTRL_HELPER_VERIFY_RANGE(cmdname, min, max) \
 CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)
 
+/*! Helper to generate static GET function for string
+ *  \param[in] cmdname symbol name of the command related function
+ *  \param[in] dtype name of outer struct of user data
+ *  \param[in] element name of field within \a dtype */
 #define CTRL_HELPER_GET_STRING(cmdname, dtype, element) \
 static int get_##cmdname(struct ctrl_cmd *cmd, void *_data) \
 { \
@@ -168,6 +215,11 @@ static int get_##cmdname(struct ctrl_cmd *cmd, void *_data) \
 	} \
 	return CTRL_CMD_REPLY; \
 }
+
+/*! Helper to generate static SET function for string
+ *  \param[in] cmdname symbol name of the command related function
+ *  \param[in] dtype name of outer struct of user data
+ *  \param[in] element name of field within \a dtype */
 #define CTRL_HELPER_SET_STRING(cmdname, dtype, element) \
 static int set_##cmdname(struct ctrl_cmd *cmd, void *_data) \
 { \
@@ -175,17 +227,31 @@ static int set_##cmdname(struct ctrl_cmd *cmd, void *_data) \
 	osmo_talloc_replace_string(cmd->node, &data->element, cmd->value); \
 	return get_##cmdname(cmd, _data); \
 }
+
+/*! Helper to generate GET, SET, VERIFY + ctrl_cmd_element for string
+ *  \param[in] cmdname symbol name of the command related function
+ *  \param[in] cmdstr string name exposed on CTRL
+ *  \param[in] dtype name of outer struct of user data
+ *  \param[in] element name of field within \a dtype
+ *  \param[in] min minimum permitted integer value
+ *  \param[in] max maximum permitted integer value */
 #define CTRL_CMD_DEFINE_STRING(cmdname, cmdstr, dtype, element) \
 	CTRL_HELPER_GET_STRING(cmdname, dtype, element) \
 	CTRL_HELPER_SET_STRING(cmdname, dtype, element) \
 CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, NULL)
 
+/*! Declare a read-write attribute. Declares get, set, verify.
+ *  \param[in] cmdname symbol name of the command related functions/structures
+ *  \param[in] cmdstr string name exposed on CTRL */
 #define CTRL_CMD_DEFINE(cmdname, cmdstr) \
 static int get_##cmdname(struct ctrl_cmd *cmd, void *data); \
 static int set_##cmdname(struct ctrl_cmd *cmd, void *data); \
 static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *data); \
 CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)
 
+/*! Define a read-only attribute. Declares get, implements set+verify
+ *  \param[in] cmdname symbol name of the command related functions/structures
+ *  \param[in] cmdstr string name exposed on CTRL */
 #define CTRL_CMD_DEFINE_RO(cmdname, cmdstr) \
 static int get_##cmdname(struct ctrl_cmd *cmd, void *data);		\
 static int set_##cmdname(struct ctrl_cmd *cmd, void *data)	\
@@ -200,6 +266,9 @@ static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *data)
 }									\
 CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)
 
+/*! Define a write-only attribute. Declares set+verify, implements read call-back
+ *  \param[in] cmdname symbol name of the command related functions/structures
+ *  \param[in] cmdstr string name exposed on CTRL */
 #define CTRL_CMD_DEFINE_WO(cmdname, cmdstr)					\
 static int set_##cmdname(struct ctrl_cmd *cmd, void *data);			\
 static int get_##cmdname(struct ctrl_cmd *cmd, void *data)			\
@@ -210,7 +279,9 @@ static int get_##cmdname(struct ctrl_cmd *cmd, void *data)			\
 static int verify_##cmdname(struct ctrl_cmd *cmd, const char *val, void *data);	\
 CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)
 
-
+/*! Define a write-only attribute without verify. Declares set, implements read+verify
+ *  \param[in] cmdname symbol name of the command related functions/structures
+ *  \param[in] cmdstr string name exposed on CTRL */
 #define CTRL_CMD_DEFINE_WO_NOVRF(cmdname, cmdstr)				\
 static int set_##cmdname(struct ctrl_cmd *cmd, void *data);			\
 static int get_##cmdname(struct ctrl_cmd *cmd, void *data)			\