doxygen: Add (partial) VTY API documentation

1 files changed, 39 insertions, 6 deletions

diff --git a/src/vty/vty.c b/src/vty/vty.c
index 1f3237ad..56e0088c 100644
--- a/src/vty/vty.c
+++ b/src/vty/vty.c
@@ -18,6 +18,11 @@
 #include <osmocom/vty/buffer.h>
 #include <osmocom/core/talloc.h>
 
+/* \addtogroup vty
+ * @{
+ */
+/*! \file vty.c */
+
 #define SYSCONFDIR "/usr/local/etc"
 
 /* our callback, located in telnet_interface.c */
@@ -44,7 +49,7 @@ static void vty_clear_buf(struct vty *vty)
 	memset(vty->buf, 0, vty->max);
 }
 
-/* Allocate new vty struct. */
+/*! \brief Allocate a new vty interface structure */
 struct vty *vty_new(void)
 {
 	struct vty *new = talloc_zero(tall_vty_ctx, struct vty);
@@ -137,7 +142,7 @@ static void vty_auth(struct vty *vty, char *buf)
 	}
 }
 
-/* Close vty interface. */
+/*! \brief Close a given vty interface. */
 void vty_close(struct vty *vty)
 {
 	int i;
@@ -178,13 +183,17 @@ void vty_close(struct vty *vty)
 	talloc_free(vty);
 }
 
+/*! \brief Return if this VTY is a shell or not */
 int vty_shell(struct vty *vty)
 {
 	return vty->type == VTY_SHELL ? 1 : 0;
 }
 
 
-/* VTY standard output function. */
+/*! \brief VTY standard output function
+ *  \param[in] vty VTY to which we should print
+ *  \param[in] format variable-length format string
+ */
 int vty_out(struct vty *vty, const char *format, ...)
 {
 	va_list args;
@@ -241,6 +250,7 @@ int vty_out(struct vty *vty, const char *format, ...)
 	return len;
 }
 
+/*! \brief print a newline on the given VTY */
 int vty_out_newline(struct vty *vty)
 {
 	char *p = vty_newline(vty);
@@ -248,15 +258,24 @@ int vty_out_newline(struct vty *vty)
 	return 0;
 }
 
+/*! \brief return the current index of a given VTY */
 void *vty_current_index(struct vty *vty)
 {
 	return vty->index;
 }
+
+/*! \brief return the current node of a given VTY */
 int vty_current_node(struct vty *vty)
 {
 	return vty->node;
 }
 
+/*! \brief Lock the configuration to a given VTY
+ *  \param[in] vty VTY to which the config shall be locked
+ *  \returns 1 on success, 0 on error
+ *
+ * This shall be used to make sure only one VTY at a given time has
+ * access to modify the configuration */
 int vty_config_lock(struct vty *vty)
 {
 	if (vty_config == 0) {
@@ -266,6 +285,10 @@ int vty_config_lock(struct vty *vty)
 	return vty->config;
 }
 
+/*! \brief Unlock the configuration from a given VTY
+ *  \param[in] vty VTY from which the configuration shall be unlocked
+ *  \returns 0 in case of success
+ */
 int vty_config_unlock(struct vty *vty)
 {
 	if (vty_config == 1 && vty->config == 1) {
@@ -1182,7 +1205,7 @@ static void vty_buffer_reset(struct vty *vty)
 	vty_redraw_line(vty);
 }
 
-/* Read data via vty socket. */
+/*! \brief Read data via vty socket. */
 int vty_read(struct vty *vty)
 {
 	int i;
@@ -1401,7 +1424,7 @@ vty_read_file(FILE *confp, void *priv)
 	return 0;
 }
 
-/* Create new vty structure. */
+/*! \brief Create new vty structure. */
 struct vty *
 vty_create (int vty_sock, void *priv)
 {
@@ -1590,7 +1613,7 @@ struct cmd_node vty_node = {
 	1,
 };
 
-/* Reset all VTY status. */
+/*! \brief Reset all VTY status. */
 void vty_reset(void)
 {
 	unsigned int i;
@@ -1647,6 +1670,10 @@ void vty_init_vtysh(void)
 }
 
 extern void *tall_bsc_ctx;
+
+/*! \brief Initialize VTY layer
+ *  \param[in] app_info application information
+ */
 /* Install vty's own commands like `who' command. */
 void vty_init(struct vty_app_info *app_info)
 {
@@ -1680,6 +1707,10 @@ void vty_init(struct vty_app_info *app_info)
 	install_element(VTY_NODE, &no_vty_login_cmd);
 }
 
+/*! \brief Read the configuration file using the VTY code
+ *  \param[in] file_name file name of the configuration file
+ *  \param[in] priv private data to be passed to \ref vty_read_file
+ */
 int vty_read_config_file(const char *file_name, void *priv)
 {
 	FILE *cfile;
@@ -1696,3 +1727,5 @@ int vty_read_config_file(const char *file_name, void *priv)
 
 	return rc;
 }
+
+/*! }@ */