From 9382718f509b6804e852e68f40102a3695900935 Mon Sep 17 00:00:00 2001
From: Sean Bright <sean.bright@gmail.com>
Date: Mon, 20 Jan 2020 12:18:17 -0500
Subject: [PATCH] res_statsd: Document that res_statsd does nothing on its own

ASTERISK-24484 #close
Reported by: Dan Jenkins

Change-Id: I05f298904511d6739aefb1486b6fcbee27efa9ec
---
 res/res_statsd.c | 35 ++++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/res/res_statsd.c b/res/res_statsd.c
index f94876ef88..8314cc9c0b 100644
--- 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>
@@ -288,13 +301,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;
 		}
 	}
@@ -302,7 +315,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);
 
@@ -311,7 +324,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;
@@ -394,7 +407,7 @@ static int reload_module(void)
 /* The priority of this module is set to be as low as possible, since it 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,