From 96e2a00d7a9044d0b1a83909c11d8f24955bc7c8 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Mon, 12 Jun 2017 21:44:18 +0200 Subject: 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 --- src/vty/command.c | 3 ++- src/vty/fsm_vty.c | 12 +++++++++++ src/vty/logging_vty.c | 12 +++++++++++ src/vty/stats_vty.c | 11 ++++++++++ src/vty/telnet_interface.c | 6 ++++++ src/vty/utils.c | 50 ++++++++++++++++++++++++++++------------------ src/vty/vector.c | 7 +++++++ src/vty/vty.c | 2 +- 8 files changed, 82 insertions(+), 21 deletions(-) (limited to 'src/vty') 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 /*! \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 #include +/*! \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 #include +/*! \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 -- cgit v1.2.3