res_statsd: Document that res_statsd does nothing on its own

ASTERISK-24484 #close
Reported by: Dan Jenkins

Change-Id: I05f298904511d6739aefb1486b6fcbee27efa9ec

diff --git a/res/res_statsd.c b/res/res_statsd.c
index 01a1fd867aa91cf5fb89133e6c57c7e33ef4d86a..bdb3d6fd97f838ea668d9a09e5e8465bcedbb9b4 100644 (file)
--- a/res/res_statsd.c
+++ b/res/res_statsd.c
@@ -17,7 +17,7 @@
  */
 
 /*!
- * \brief Support for publishing to a statsd server.
+ * \brief Support for publishing to a StatsD server.
  *
  * \author David M. Lee, II <dlee@digium.com>
  * \since 12
@@ -29,21 +29,34 @@
 
 /*** DOCUMENTATION
        <configInfo name="res_statsd" language="en_US">
-               <synopsis>Statsd client.</synopsis>
+               <synopsis>StatsD client</synopsis>
+               <description>
+                       <para>The <literal>res_statsd</literal> module provides an API that
+                       allows Asterisk and its modules to send statistics to a StatsD
+                       server. It only provides a means to communicate with a StatsD server
+                       and does not send any metrics of its own.</para>
+                       <para>An example module, <literal>res_chan_stats</literal>, is
+                       provided which uses the API exposed by this module to send channel
+                       statistics to the configured StatsD server.</para>
+                       <para>More information about StatsD can be found at
+                       https://github.com/statsd/statsd</para>
+               </description>
                <configFile name="statsd.conf">
                        <configObject name="global">
                                <synopsis>Global configuration settings</synopsis>
                                <configOption name="enabled">
-                                       <synopsis>Enable/disable the statsd module</synopsis>
+                                       <synopsis>Enable/disable the StatsD module</synopsis>
                                </configOption>
                                <configOption name="server">
-                                       <synopsis>Address of the statsd server</synopsis>
+                                       <synopsis>Address of the StatsD server</synopsis>
                                </configOption>
                                <configOption name="prefix">
                                        <synopsis>Prefix to prepend to every metric</synopsis>
                                </configOption>
                                <configOption name="add_newline">
-                                       <synopsis>Append a newline to every event. This is useful if you want to fake out a server using netcat (nc -lu 8125)</synopsis>
+                                       <synopsis>Append a newline to every event. This is useful if
+                                       you want to fake out a server using netcat
+                                       (nc -lu 8125)</synopsis>
                                </configOption>
                        </configObject>
                </configFile>
@@ -286,13 +299,13 @@ static int statsd_init(void)
 
        ast_assert(is_enabled());
 
-       ast_debug(3, "Configuring statsd client.\n");
+       ast_debug(3, "Configuring StatsD client.\n");
 
        if (socket_fd == -1) {
-               ast_debug(3, "Creating statsd socket.\n");
+               ast_debug(3, "Creating StatsD socket.\n");
                socket_fd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
                if (socket_fd == -1) {
-                       perror("Error creating statsd socket");
+                       perror("Error creating StatsD socket");
                        return -1;
                }
        }
@@ -300,7 +313,7 @@ static int statsd_init(void)
        conf_server(cfg, &statsd_server);
        server = ast_sockaddr_stringify_fmt(&statsd_server,
                AST_SOCKADDR_STR_DEFAULT);
-       ast_debug(3, "  statsd server = %s.\n", server);
+       ast_debug(3, "  StatsD server = %s.\n", server);
        ast_debug(3, "  add newline = %s\n", AST_YESNO(cfg->global->add_newline));
        ast_debug(3, "  prefix = %s\n", cfg->global->prefix);
 
@@ -309,7 +322,7 @@ static int statsd_init(void)
 
 static void statsd_shutdown(void)
 {
-       ast_debug(3, "Shutting down statsd client.\n");
+       ast_debug(3, "Shutting down StatsD client.\n");
        if (socket_fd != -1) {
                close(socket_fd);
                socket_fd = -1;
@@ -405,7 +418,7 @@ static int reload_module(void)
 /* The priority of this module is set just after realtime, since it loads
  * configuration and could be used by any other sort of module.
  */
-AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER, "Statsd client support",
+AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER, "StatsD client support",
        .support_level = AST_MODULE_SUPPORT_EXTENDED,
        .load = load_module,
        .unload = unload_module,