Doxygen Cleanup

Start adding configuration file linking and pages.  Add module loading doxygen block.

Breaking up commits to keep it easy to track

(issue ASTERISK-20259)


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@374166 65c4cc65-6c06-0410-ace0-fbb531ad65f3

13 files changed, 256 insertions, 21 deletions

diff --git a/channels/chan_alsa.c b/channels/chan_alsa.c
index 71d51adf4..ec4fa8c33 100644
--- a/channels/chan_alsa.c
+++ b/channels/chan_alsa.c
@@ -21,12 +21,18 @@
  *
  * \author Matthew Fredrickson <creslin@digium.com>
  *
- * \par See also
- * \arg Config_alsa
- *
  * \ingroup channel_drivers
  */
 
+/*!
+ * \li The channel chan_alsa uses the configuration file \ref alsa.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page alsa.conf alsa.conf
+ * \verbinclude alsa.conf.sample
+ */
+
 /*** MODULEINFO
 	<depend>alsa</depend>
 	<support_level>extended</support_level>
@@ -925,6 +931,16 @@ static struct ast_cli_entry cli_alsa[] = {
 	AST_CLI_DEFINE(console_mute, "Disable/Enable mic input"),
 };
 
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	struct ast_config *cfg;
diff --git a/channels/chan_console.c b/channels/chan_console.c
index 5eef4c3c8..d936084e7 100644
--- a/channels/chan_console.c
+++ b/channels/chan_console.c
@@ -47,6 +47,15 @@
  * - console_video support
  */
 
+/*!
+ * \li The channel chan_console uses the configuration file \ref console.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page console.conf console.conf
+ * \verbinclude console.conf.sample
+ */
+
 /*** MODULEINFO
 	<depend>portaudio</depend>
 	<support_level>extended</support_level>
@@ -1469,6 +1478,16 @@ static int unload_module(void)
 	return 0;
 }
 
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	struct ast_format tmpfmt;
diff --git a/channels/chan_dahdi.c b/channels/chan_dahdi.c
index f669e2ead..678312631 100644
--- a/channels/chan_dahdi.c
+++ b/channels/chan_dahdi.c
@@ -29,14 +29,20 @@
  * You need to install libraries before you attempt to compile
  * and install the DAHDI channel.
  *
- * \par See also
- * \arg \ref Config_dahdi
- *
  * \ingroup channel_drivers
  *
  * \todo Deprecate the "musiconhold" configuration option post 1.4
  */
 
+/*!
+ * \li The channel chan_dahdi uses the configuration file \ref chan_dahdi.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page chan_dahdi.conf chan_dahdi.conf
+ * \verbinclude chan_dahdi.conf.sample
+ */
+
 /*** MODULEINFO
 	<use type="module">res_smdi</use>
 	<depend>dahdi</depend>
@@ -19096,6 +19102,16 @@ static const struct ast_data_entry dahdi_data_providers[] = {
 	AST_DATA_ENTRY("asterisk/channel/dahdi/version", &dahdi_version_data_provider)
 };
 
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	int res;
diff --git a/channels/chan_gtalk.c b/channels/chan_gtalk.c
index f30a3413b..d257f0f3d 100644
--- a/channels/chan_gtalk.c
+++ b/channels/chan_gtalk.c
@@ -31,6 +31,15 @@
  * \todo Fix native bridging.
  */
 
+/*!
+ * \li The channel chan_gtalk uses the configuration file \ref gtalk.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page gtalk.conf gtalk.conf
+ * \verbinclude gtalk.conf.sample
+ */
+
 /*** MODULEINFO
         <defaultenabled>no</defaultenabled>
 	<depend>iksemel</depend>
@@ -2297,7 +2306,16 @@ static int gtalk_load_config(void)
 	return 1;
 }
 
-/*! \brief Load module into PBX, register channel */
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	struct ast_sockaddr bindaddr_tmp;
diff --git a/channels/chan_iax2.c b/channels/chan_iax2.c
index 630918480..961efa7df 100644
--- a/channels/chan_iax2.c
+++ b/channels/chan_iax2.c
@@ -31,6 +31,15 @@
  * \todo Implement musicclass settings for IAX2 devices
  */
 
+/*!
+ * \li The channel chan_iax uses the configuration file \ref iax.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page iax.conf iax.conf
+ * \verbinclude iax.conf.sample
+ */
+
 /*** MODULEINFO
 	<use type="external">crypto</use>
 	<support_level>core</support_level>
@@ -14888,7 +14897,16 @@ static const struct ast_data_entry iax2_data_providers[] = {
 	AST_DATA_ENTRY("asterisk/channel/iax2/users", &users_data_provider),
 };
 
-/*! \brief Load IAX2 module, load configuraiton ---*/
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	static const char config[] = "iax.conf";
diff --git a/channels/chan_jingle.c b/channels/chan_jingle.c
index dfc2ea9b3..d5fe3c019 100644
--- a/channels/chan_jingle.c
+++ b/channels/chan_jingle.c
@@ -27,6 +27,15 @@
  * \ingroup channel_drivers
  */
 
+/*!
+ * \li The channel chan_jingle uses the configuration file \ref jingle.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page jingle.conf jingle.conf
+ * \verbinclude jingle.conf.sample
+ */
+
 /*** MODULEINFO
 	<depend>iksemel</depend>
 	<depend>res_jabber</depend>
@@ -1936,7 +1945,16 @@ static int jingle_load_config(void)
 	return 1;
 }
 
-/*! \brief Load module into PBX, register channel */
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	struct ast_sockaddr ourip_tmp;
diff --git a/channels/chan_mgcp.c b/channels/chan_mgcp.c
index 13a518071..1655399b1 100644
--- a/channels/chan_mgcp.c
+++ b/channels/chan_mgcp.c
@@ -22,12 +22,18 @@
  *
  * \author Mark Spencer <markster@digium.com>
  *
- * \par See also
- * \arg \ref Config_mgcp
- *
  * \ingroup channel_drivers
  */
 
+/*!
+ * \li The channel chan_mgcp uses the configuration file \ref mgcp.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page mgcp.conf mgcp.conf
+ * \verbinclude mgcp.conf.sample
+ */
+
 /*** MODULEINFO
         <use type="module">res_pktccops</use>
 	<support_level>extended</support_level>
@@ -4794,7 +4800,16 @@ static int reload_config(int reload)
 	return 0;
 }
 
-/*! \brief  load_module: PBX load module - initialization ---*/
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	struct ast_format tmpfmt;
diff --git a/channels/chan_misdn.c b/channels/chan_misdn.c
index 2f644a86e..5a36e9365 100644
--- a/channels/chan_misdn.c
+++ b/channels/chan_misdn.c
@@ -30,6 +30,15 @@
  */
 
 /*!
+ * \li The channel chan_misdn uses the configuration file \ref misdn.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page misdn.conf misdn.conf
+ * \verbinclude misdn.conf.sample
+ */
+
+/*!
  * \note
  * To use the CCBS/CCNR supplementary service feature and other
  * supplementary services using FACILITY messages requires a
@@ -11275,6 +11284,16 @@ static int unload_module(void)
 	return 0;
 }
 
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	int i, port;
diff --git a/channels/chan_motif.c b/channels/chan_motif.c
index 77c446723..6c62f6aad 100644
--- a/channels/chan_motif.c
+++ b/channels/chan_motif.c
@@ -27,6 +27,15 @@
  * \ingroup channel_drivers
  */
 
+/*!
+ * \li The channel chan_motif uses the configuration file \ref motif.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page motif.conf motif.conf
+ * \verbinclude motif.conf.sample
+ */
+
 /*** MODULEINFO
 	<depend>iksemel</depend>
 	<depend>res_xmpp</depend>
@@ -2498,7 +2507,16 @@ static int custom_transport_handler(const struct aco_option *opt, struct ast_var
 	return 0;
 }
 
-/*! \brief Load module into PBX, register channel */
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	if (!(jingle_tech.capabilities = ast_format_cap_alloc())) {
diff --git a/channels/chan_oss.c b/channels/chan_oss.c
index 0e3b02b69..504cb902c 100644
--- a/channels/chan_oss.c
+++ b/channels/chan_oss.c
@@ -27,12 +27,18 @@
  * \author Mark Spencer <markster@digium.com>
  * \author Luigi Rizzo
  *
- * \par See also
- * \arg \ref Config_oss
- *
  * \ingroup channel_drivers
  */
 
+/*!
+ * \li The channel chan_oss uses the configuration file \ref oss.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page oss.conf oss.conf
+ * \verbinclude oss.conf.sample
+ */
+
 /*** MODULEINFO
 	<depend>oss</depend>
 	<support_level>extended</support_level>
@@ -1436,6 +1442,16 @@ error:
 #endif
 }
 
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	struct ast_config *cfg = NULL;
diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index a1edca9f4..8e071e11d 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -92,6 +92,19 @@
  * the sip_hangup() function
  */
 
+/*! 
+ * \li The channel chan_sip uses configuration files \ref sip.conf and \ref sip_notify.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page sip.conf sip.conf
+ * \verbinclude sip.conf.sample
+ */
+
+/*! \page sip_notify.conf sip_notify.conf
+ * \verbinclude sip_notify.conf.sample
+ */
+
 /*!
  * \page sip_tcp_tls SIP TCP and TLS support
  *
@@ -815,13 +828,15 @@ static unsigned char global_refer_addheaders; /*!< Add extra headers to outgoing
 static int can_parse_xml;
 
 /*! \name Object counters @{
- *  \bug These counters are not handled in a thread-safe way ast_atomic_fetchadd_int()
- *  should be used to modify these values. */
+ *
+ * \bug These counters are not handled in a thread-safe way ast_atomic_fetchadd_int()
+ * should be used to modify these values.
+ */
 static int speerobjs = 0;     /*!< Static peers */
 static int rpeerobjs = 0;     /*!< Realtime peers */
 static int apeerobjs = 0;     /*!< Autocreated peer objects */
 static int regobjs = 0;       /*!< Registry objects */
-/* }@ */
+/*! @} */
 
 static struct ast_flags global_flags[3] = {{0}};  /*!< global SIP_ flags */
 static int global_t38_maxdatagram;                /*!< global T.38 FaxMaxDatagram override */
@@ -33306,7 +33321,16 @@ static const struct ast_data_entry sip_data_providers[] = {
 	AST_DATA_ENTRY("asterisk/channel/sip/peers", &peers_data_provider),
 };
 
-/*! \brief PBX load module - initialization */
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	ast_verbose("SIP channel loading...\n");
diff --git a/channels/chan_skinny.c b/channels/chan_skinny.c
index c30338ae9..a62de91f3 100644
--- a/channels/chan_skinny.c
+++ b/channels/chan_skinny.c
@@ -25,6 +25,15 @@
  * \ingroup channel_drivers
  */
 
+/*!
+ * \li The channel chan_skinny uses the configuration file \ref skinny.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page skinny.conf skinny.conf
+ * \verbinclude skinny.conf.sample
+ */
+
 /*** MODULEINFO
 	<support_level>extended</support_level>
  ***/
@@ -7958,6 +7967,16 @@ int skinny_reload(void)
         return 0;
 }
 
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static int load_module(void)
 {
 	int res = 0;
diff --git a/channels/chan_vpb.cc b/channels/chan_vpb.cc
index 378c44773..d4d08c097 100644
--- a/channels/chan_vpb.cc
+++ b/channels/chan_vpb.cc
@@ -29,6 +29,15 @@
  * \ingroup channel_drivers
  */
 
+/*!
+ * \li The channel chan_vpb uses the configuration file \ref vpb.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page vpb.conf vpb.conf
+ * \verbinclude vpb.conf.sample
+ */
+
 /*** MODULEINFO
 	<depend>vpb</depend>
 	<defaultenabled>no</defaultenabled>
@@ -2648,6 +2657,16 @@ static int unload_module(void)
 	return 0;
 }
 
+/*!
+ * \brief Load the module
+ *
+ * Module loading including tests for configuration or dependencies.
+ * This function can return AST_MODULE_LOAD_FAILURE, AST_MODULE_LOAD_DECLINE,
+ * or AST_MODULE_LOAD_SUCCESS. If a dependency or environment variable fails
+ * tests return AST_MODULE_LOAD_FAILURE. If the module can not load the 
+ * configuration file or other non-critical problem return 
+ * AST_MODULE_LOAD_DECLINE. On success return AST_MODULE_LOAD_SUCCESS.
+ */
 static enum ast_module_load_result load_module()
 {
 	struct ast_config *cfg;