update/extend doxygen documentation

It's a pity that even with this patch we still are fare away from having
the whole API documented.  However, at least we have a more solid
foundation.  Updates not only extend the documentation, but also make
sure it is rendered properly in the doxygen HTML.

Change-Id: I1344bd1a6869fb00de7c1899a8db93bba9bafce3

8 files changed, 82 insertions, 21 deletions

diff --git a/src/vty/command.c b/src/vty/command.c
index 587bd626..e50706e8 100644
--- a/src/vty/command.c
+++ b/src/vty/command.c
@@ -42,7 +42,8 @@ Boston, MA  02110-1301, USA. */
 #include <osmocom/core/utils.h>
 
 /*! \addtogroup command
- * @{
+ *  @{
+ *  \brief VTY command handling
  */
 /*! \file command.c */
 
diff --git a/src/vty/fsm_vty.c b/src/vty/fsm_vty.c
index 422de9d9..3824fe8c 100644
--- a/src/vty/fsm_vty.c
+++ b/src/vty/fsm_vty.c
@@ -33,6 +33,16 @@
 #include <osmocom/core/logging.h>
 #include <osmocom/core/linuxlist.h>
 
+/*! \addtogroup fsm
+ *  @{
+ *  \brief VTY interface for Osmocom FSM
+ *
+ *  This is code implementing generic VTY access to Osmocom FSMs from
+ *  libosmocore.  This means that any application can expose all state
+ *  of all instances of all registered FSM classes by calling a single
+ *  command during startup: \ref osmo_fsm_vty_add_cmds
+ */
+
 /* we don't want to add this to a public header file; this is simply
  * exported by libosmocore and used by libmsomvty but not for public
  * consumption. */
@@ -175,3 +185,5 @@ void osmo_fsm_vty_add_cmds(void)
 	install_element_ve(&show_fsm_inst_cmd);
 	install_element_ve(&show_fsm_insts_cmd);
 }
+
+/*! @} */
diff --git a/src/vty/logging_vty.c b/src/vty/logging_vty.c
index 7ec212e7..8c8a3235 100644
--- a/src/vty/logging_vty.c
+++ b/src/vty/logging_vty.c
@@ -39,6 +39,16 @@
 
 #define LOG_STR "Configure logging sub-system\n"
 
+/*! \addtogroup logging
+ *  @{
+ *  \brief Configuration of logging from VTY
+ *
+ *  This module implements functions that permit configuration of
+ *  the libosmocore logging framework from VTY commands.  This applies
+ *  both to logging to the VTY (telnet sessions), as well as logging to
+ *  other targets, such as sysslog, file, gsmtap, ...
+ */
+
 extern const struct log_info *osmo_log_info;
 
 static void _vty_output(struct log_target *tgt,
@@ -778,3 +788,5 @@ void logging_vty_add_cmds()
 #endif
 	install_element(CONFIG_NODE, &cfg_log_gsmtap_cmd);
 }
+
+/* @} */
diff --git a/src/vty/stats_vty.c b/src/vty/stats_vty.c
index c03546b8..af69289f 100644
--- a/src/vty/stats_vty.c
+++ b/src/vty/stats_vty.c
@@ -41,6 +41,11 @@
 
 #define SHOW_STATS_STR "Show statistical values\n"
 
+/*! \addtogroup stats
+ *  @{
+ *  \brief VTY interface for statsd / statistic items
+ */
+
 /* containing version info */
 extern struct host host;
 
@@ -571,6 +576,10 @@ static int config_write_stats(struct vty *vty)
 	return 1;
 }
 
+/*! \brief Add stats related commands to the VTY
+ *  Call this once during your application initialization if you would
+ *  like to have stats VTY commands enabled.
+ */
 void osmo_stats_vty_add_cmds()
 {
 	install_element_ve(&show_stats_cmd);
@@ -599,3 +608,5 @@ void osmo_stats_vty_add_cmds()
 
 	install_element_ve(&show_stats_asciidoc_table_cmd);
 }
+
+/*! @} */
diff --git a/src/vty/telnet_interface.c b/src/vty/telnet_interface.c
index 218f9abf..d53881a1 100644
--- a/src/vty/telnet_interface.c
+++ b/src/vty/telnet_interface.c
@@ -38,6 +38,12 @@
 
 /*! \addtogroup telnet_interface
  *  @{
+ *  \brief Telnet interface towards Osmocom VTY
+ *
+ *  This module contains the code implementing a telnet server for VTY
+ *  access.  This telnet server gets linked into each libosmovty-using
+ *  process in order to enable interactive command-line introspection,
+ *  interaction and configuration.
  */
 /*! \file telnet_interface.c */
 
diff --git a/src/vty/utils.c b/src/vty/utils.c
index 27c1a854..6772593d 100644
--- a/src/vty/utils.c
+++ b/src/vty/utils.c
@@ -82,6 +82,33 @@ void vty_out_rate_ctr_group(struct vty *vty, const char *prefix,
 	rate_ctr_for_each_counter(ctrg, rate_ctr_handler, &vctx);
 }
 
+static int rate_ctr_group_handler(struct rate_ctr_group *ctrg, void *vctx_)
+{
+	struct vty_out_context *vctx = vctx_;
+	struct vty *vty = vctx->vty;
+
+	if (ctrg->desc->class_id > vctx->max_level)
+		return 0;
+
+	if (ctrg->idx)
+		vty_out(vty, "%s%s (%d):%s", vctx->prefix,
+			ctrg->desc->group_description, ctrg->idx, VTY_NEWLINE);
+	else
+		vty_out(vty, "%s%s:%s", vctx->prefix,
+			ctrg->desc->group_description, VTY_NEWLINE);
+
+	rate_ctr_for_each_counter(ctrg, rate_ctr_handler, vctx);
+
+	return 0;
+}
+
+/*! @} */
+
+
+/*! \addtogroup stats
+ *  @{
+ */
+
 static int osmo_stat_item_handler(
 	struct osmo_stat_item_group *statg, struct osmo_stat_item *item, void *vctx_)
 {
@@ -135,25 +162,11 @@ static int osmo_stat_item_group_handler(struct osmo_stat_item_group *statg, void
 	return 0;
 }
 
-static int rate_ctr_group_handler(struct rate_ctr_group *ctrg, void *vctx_)
-{
-	struct vty_out_context *vctx = vctx_;
-	struct vty *vty = vctx->vty;
-
-	if (ctrg->desc->class_id > vctx->max_level)
-		return 0;
-
-	if (ctrg->idx)
-		vty_out(vty, "%s%s (%d):%s", vctx->prefix,
-			ctrg->desc->group_description, ctrg->idx, VTY_NEWLINE);
-	else
-		vty_out(vty, "%s%s:%s", vctx->prefix,
-			ctrg->desc->group_description, VTY_NEWLINE);
-
-	rate_ctr_for_each_counter(ctrg, rate_ctr_handler, vctx);
+/*! @} */
 
-	return 0;
-}
+/*! \addtogroup vty
+ *  @{
+ */
 
 static int handle_counter(struct osmo_counter *counter, void *vctx_)
 {
@@ -239,5 +252,4 @@ err:
 	return str;
 }
 
-
 /*! @} */
diff --git a/src/vty/vector.c b/src/vty/vector.c
index c5a99af3..b95e15c3 100644
--- a/src/vty/vector.c
+++ b/src/vty/vector.c
@@ -27,6 +27,11 @@
 #include <osmocom/core/talloc.h>
 #include <string.h>
 
+/*! \addtogroup vector
+ *  @{
+ *  \brief Generic vector routines, used by VTY internally
+ */
+
 void *tall_vty_vec_ctx;
 
 /* Initialize vector : allocate memory and return vector. */
@@ -190,3 +195,5 @@ unsigned int vector_count(vector v)
 
 	return count;
 }
+
+/*! @} */
diff --git a/src/vty/vty.c b/src/vty/vty.c
index 01d5ec09..2ec9538c 100644
--- a/src/vty/vty.c
+++ b/src/vty/vty.c
@@ -14,7 +14,7 @@
  * routines in libosmovty are not thread-safe.  If you must use them in
  * a multi-threaded context, you have to add your own locking.
  *
- * libosmocovty is developed as part of the Osmocom (Open Source Mobile
+ * libosmovty is developed as part of the Osmocom (Open Source Mobile
  * Communications) project, a community-based, collaborative development
  * project to create Free and Open Source implementations of mobile
  * communications systems.  For more information about Osmocom, please