ctrl: Add doxygen API documentation; generate html from it

Closes: OS#3293
Change-Id: I8dc2f24d4bf557ff7bb0f2f46881f9f8d9d7f86f

2 files changed, 67 insertions, 4 deletions

diff --git a/src/ctrl/control_cmd.c b/src/ctrl/control_cmd.c
index fb0cd2b7..bff4d17d 100644
--- a/src/ctrl/control_cmd.c
+++ b/src/ctrl/control_cmd.c
@@ -89,6 +89,12 @@ static struct ctrl_cmd_element *ctrl_cmd_get_element_match(vector vline, vector
 	return NULL;
 }
 
+/*! Execute a given received command
+ *  \param[in] vline vector representing the available/registered commands
+ *  \param[inout] command parsed received command to be executed
+ *  \param[in] node CTRL interface node
+ *  \param[in] data opaque data passed to verify(), get() and set() call-backs
+ *  \returns CTRL_CMD_HANDLED or CTRL_CMD_REPLY;  CTRL_CMD_ERROR on error */
 int ctrl_cmd_exec(vector vline, struct ctrl_cmd *command, vector node, void *data)
 {
 	int ret = CTRL_CMD_ERROR;
@@ -200,6 +206,10 @@ failure:
 	talloc_free(cmd->command);
 }
 
+/*! Install a given command definition at a given CTRL node.
+ *  \param[in] node CTRL node at whihc \a cmd is to be installed
+ *  \param[in] cmd command definition to be installed
+ *  \returns 0 on success; negative on error */
 int ctrl_cmd_install(enum ctrl_node_type node, struct ctrl_cmd_element *cmd)
 {
 	vector cmds_vec;
@@ -221,6 +231,10 @@ int ctrl_cmd_install(enum ctrl_node_type node, struct ctrl_cmd_element *cmd)
 	return 0;
 }
 
+/*! Allocate a control command of given \a type.
+ *  \param[in] ctx talloc context from which to allocate
+ *  \param[in] type command type to set after allocation
+ *  \returns callee-allocated \ref ctrl_cmd. Caller must talloc_free() it. */
 struct ctrl_cmd *ctrl_cmd_create(void *ctx, enum ctrl_type type)
 {
 	struct ctrl_cmd *cmd;
@@ -233,6 +247,10 @@ struct ctrl_cmd *ctrl_cmd_create(void *ctx, enum ctrl_type type)
 	return cmd;
 }
 
+/*! Perform a deepl copy of the given \a cmd, allocating memory from \a ctx.
+ *  \param[in] ctx talloc context from which to allocate
+ *  \param[in cmd CTRL command to be copied
+ *  \returns deep copy of \a cmd on success; NULL on error */
 struct ctrl_cmd *ctrl_cmd_cpy(void *ctx, struct ctrl_cmd *cmd)
 {
 	struct ctrl_cmd *cmd2;
@@ -269,7 +287,10 @@ err:
 	return NULL;
 }
 
-/*! Parse CTRL command struct from msgb, return NULL on any error.
+/*! Parse/Decode CTRL from \ref msgb into command struct.
+ *  \param[in] ctx talloc context from which to allocate
+ *  \param[in] msg message buffer containing command to be decoded
+ *  \returns callee-allocated decoded CTRL command; NULL on allocation or other failure
  * The caller is responsible to talloc_free() the returned struct pointer. */
 struct ctrl_cmd *ctrl_cmd_parse(void *ctx, struct msgb *msg)
 {
@@ -290,8 +311,11 @@ static bool id_str_valid(const char *str)
 	return true;
 }
 
-/*! Parse CTRL command struct from msgb, return ctrl->type == CTRL_TYPE_ERROR and an error message in
- * ctrl->reply on any error.
+/*! Parse/Decode CTRL from \ref msgb into command struct.
+ *  \param[in] ctx talloc context from which to allocate
+ *  \param[in] msg message buffer containing command to be decoded
+ *  \returns callee-allocated decoded CTRL command; NULL on allocation failure,
+ *  ctrl->type == CTRL_TYPE_ERROR and an error message in ctrl->reply on any error.
  * The caller is responsible to talloc_free() the returned struct pointer. */
 struct ctrl_cmd *ctrl_cmd_parse2(void *ctx, struct msgb *msg)
 {
@@ -466,6 +490,9 @@ err:
 	return cmd;
 }
 
+/*! Encode a given CTRL command from its parsed form into a message buffer.
+ *  \param[in] cmd decoded/parsed form of to-be-encoded command
+ *  \returns callee-allocated message buffer containing the encoded \a cmd; NULL on error */
 struct msgb *ctrl_cmd_make(struct ctrl_cmd *cmd)
 {
 	struct msgb *msg;
@@ -556,6 +583,15 @@ err:
 	return NULL;
 }
 
+/*! Build a deferred control command state and keep it the per-connection list of deferred commands.
+ *  This function is typically called by a ctrl command handler that wishes to defer returning a
+ *  response.  The reutnred state can later be used to check if the deferred command is still alive,
+ *  and to respond to the specific command.  This only works to defer the response to GET and SET.
+ *  \param[in] ctx talloc context from whihc to allocate the ctrl_cmd_def
+ *  \param[in] cmd the control command whose response is deferred
+ *  \param[in] data opaque, user-defined pointer
+ *  \param[in] secs number of seconds until the command times out
+ *  \returns callee-allocated ctrl_cmd_def */
 struct ctrl_cmd_def *
 ctrl_cmd_def_make(const void *ctx, struct ctrl_cmd *cmd, void *data, unsigned int secs)
 {
@@ -576,6 +612,9 @@ ctrl_cmd_def_make(const void *ctx, struct ctrl_cmd *cmd, void *data, unsigned in
 	return cd;
 }
 
+/*! Determine if the given deferred control command is still alive or a zombie.
+ *  \param[in] cd deferred ctrl command state
+ *  \returns 0 is \a cd is still alive; 1 if it's a zombie */
 int ctrl_cmd_def_is_zombie(struct ctrl_cmd_def *cd)
 {
 	/* luckily we're still alive */
@@ -589,6 +628,10 @@ int ctrl_cmd_def_is_zombie(struct ctrl_cmd_def *cd)
 	return 1;
 }
 
+/*! Send the response to a deferred ctrl command.
+ *  The command can only be a resply to a SET or a GET operation.
+ *  \param[in] cd deferred ctrl command state
+ *  \returns 0 if command sent successfully; negative on error */
 int ctrl_cmd_def_send(struct ctrl_cmd_def *cd)
 {
 	struct ctrl_cmd *cmd = cd->cmd;
diff --git a/src/ctrl/control_if.c b/src/ctrl/control_if.c
index 269b7b93..d3e6faca 100644
--- a/src/ctrl/control_if.c
+++ b/src/ctrl/control_if.c
@@ -75,6 +75,11 @@ struct lookup_helper {
 };
 static LLIST_HEAD(ctrl_lookup_helpers);
 
+/*! Parse ascii-encoded decimal number at vline[i]
+ *  \param[in] vline vector containing a tokenized line
+ *  \param[in] i index into the vector \a vline
+ *  \param[out] num parsed decimal integer number at vline[i]
+ *  \returns 1 on success; 0 in case of error */
 int ctrl_parse_get_num(vector vline, int i, long *num)
 {
 	char *token, *tmp;
@@ -94,7 +99,10 @@ int ctrl_parse_get_num(vector vline, int i, long *num)
 	return 1;
 }
 
-/* Send command to all  */
+/*! Send a CTRL command to all connections.
+ *  \param[in] ctrl global control handle
+ *  \param[in] cmd command to send to all connections in \ctrl
+ *  \returns number of times the command has been sent */
 int ctrl_cmd_send_to_all(struct ctrl_handle *ctrl, struct ctrl_cmd *cmd)
 {
 	struct ctrl_connection *ccon;
@@ -109,6 +117,10 @@ int ctrl_cmd_send_to_all(struct ctrl_handle *ctrl, struct ctrl_cmd *cmd)
 	return ret;
 }
 
+/*! Encode a CTRL command and append it to the given write queue
+ *  \param[inout] queue write queue to which encoded \a cmd shall be appended
+ *  \param[in] cmd decoded command representation
+ *  \returns 0 in case of success; negative on error */
 int ctrl_cmd_send(struct osmo_wqueue *queue, struct ctrl_cmd *cmd)
 {
 	int ret;
@@ -152,6 +164,9 @@ int ctrl_cmd_send_trap(struct ctrl_handle *ctrl, const char *name, char *value)
 	return r;
 }
 
+/*! Copy given \a cmd and convert copy to CTRL_TYPE_TRAP.
+ *  \param[in] cmd command to be copied
+ *  \returns pointer to newly-allocated copy of type TRAP. Allocated as sibling of \a cmd */
 struct ctrl_cmd *ctrl_cmd_trap(struct ctrl_cmd *cmd)
 {
 	struct ctrl_cmd *trap;
@@ -361,6 +376,11 @@ close_fd:
 	return -EBADF;
 }
 
+/*! Handle a received CTRL command contained in a \ref msgb.
+ *  \param[in] ctrl CTRL interface handle
+ *  \param[in] ccon CTRL connection through which the command was received
+ *  \param[in] msg message buffer containing CTRL command including IPA+IPA_EXT headers
+ *  \returns 0 on success; negative on error */
 int ctrl_handle_msg(struct ctrl_handle *ctrl, struct ctrl_connection *ccon, struct msgb *msg)
 {
 	struct ctrl_cmd *cmd;