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@374167 65c4cc65-6c06-0410-ace0-fbb531ad65f3

5 files changed, 161 insertions, 67 deletions

diff --git a/addons/app_mysql.c b/addons/app_mysql.c
index 2e9cae94a..91d300591 100644
--- a/addons/app_mysql.c
+++ b/addons/app_mysql.c
@@ -23,6 +23,16 @@
  * \ingroup applications
  */
 
+/*!
+ * \li The application app_mysql uses the configuration file \ref app_mysql.conf
+ * \addtogroup configuration_file Configuration Files
+ */
+
+/*! 
+ * \page app_mysql.conf app_mysql.conf
+ * \verbinclude app_mysql.conf.sample
+ */
+
 /*** MODULEINFO
 	<depend>mysqlclient</depend>
 	<defaultenabled>no</defaultenabled>
@@ -605,6 +615,16 @@ static int unload_module(void)
 	return ast_unregister_application(app);
 }
 
+/*!
+ * \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 MYSQLidshead *headp = &_mysql_ids_head;
diff --git a/contrib/asterisk-ng-doxygen b/contrib/asterisk-ng-doxygen
index 2f292d193..f83f76a53 100644
--- a/contrib/asterisk-ng-doxygen
+++ b/contrib/asterisk-ng-doxygen
@@ -1,4 +1,4 @@
-# Doxyfile 1.5.2
+# Doxyfile 1.7.1
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project
@@ -179,8 +179,8 @@ TAB_SIZE               = 3
 # will result in a user-defined paragraph with heading "Side Effects:".
 # You can put \n's in the value part of an alias to insert newlines.
 
-ALIASES                = "extref=\xrefitem extref \"ExtRef\" \"External references\""
-ALIASES += "AsteriskTrunkWarning=\note The information contained on this page may be out of date.  To make sure you get the most current information, please make sure that you are using the documentation generated from Asterisk trunk."
+ALIASES                = "extref=\xrefitem extref \"ExtRef\" \"External references\"" \
+                         "AsteriskTrunkWarning=\note The information contained on this page may be out of date.  To make sure you get the most current information, please make sure that you are using the documentation generated from Asterisk trunk."
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
 # sources only. Doxygen will then generate output that is more tailored for C.
@@ -1034,7 +1034,7 @@ ENUM_VALUES_PER_LINE   = 4
 # JavaScript, DHTML, CSS and frames is required (i.e. any modern browser).
 # Windows users are probably better off using the HTML help feature.
 
-GENERATE_TREEVIEW      = YES
+GENERATE_TREEVIEW      = NO
 
 # By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories,
 # and Class Hierarchy pages using a tree view instead of an ordered list.
@@ -1385,52 +1385,51 @@ PREDEFINED             = __GNUC__ \
 # The macro definition that is found in the sources will be used.
 # Use the PREDEFINED tag if you want to use a different macro definition.
 
-EXPAND_AS_DEFINED      = \
-            AST_INLINE_API \
-            AST_DECLARE_STRING_FIELDS \
-            AST_STRING_FIELD \
-            AST_THREADSTORAGE \
-            AST_THREADSTORAGE_CUSTOM \
-            AST_MODULE_INFO \
-            AST_MODULE_INFO_STANDARD \
-            __AST_MUTEX_DEFINE \
-            AST_MUTEX_DEFINE_STATIC \
-            AST_MUTEX_DEFINE_STATIC_NOTRACKING \
-            __AST_RWLOCK_DEFINE \
-            AST_RWLOCK_DEFINE_STATIC \
-            AST_LIST_HEAD \
-            AST_RWLIST_HEAD \
-            AST_LIST_HEAD_NOLOCK \
-            AST_LIST_HEAD_STATIC \
-            AST_RWLIST_HEAD_STATIC \
-            AST_LIST_HEAD_NOLOCK_STATIC \
-            AST_LIST_ENTRY \
-            AST_RWLIST_ENTRY \
-            __ASTOBJ_HASH \
-            ASTOBJ_COMPONENTS_NOLOCK_FULL \
-            ASTOBJ_COMPONENTS_NOLOCK \
-            ASTOBJ_COMPONENTS_FULL \
-            ASTOBJ_COMPONENTS \
-            AST_IVR_DECLARE_MENU \
-            AST_DECLARE_APP_ARGS \
-            AST_DEFINE_APP_ARGS_TYPE \
-            AST_APP_ARG \
-            BEGIN_OPTIONS \
-            END_OPTIONS \
-            AST_APP_OPTIONS \
-            AST_APP_OPTION \
-            AST_APP_OPTION_ARG \
-            AST_DLLIST_HEAD \
-            AST_DLLIST_HEAD_STATIC \
-            AST_DLLIST_HEAD_NOLOCK \
-            AST_DLLIST_HEAD_NOLOCK_STATIC \
-            AST_RWDLLIST_HEAD \
-            AST_RWDLLIST_HEAD_STATIC \
-            AST_DLLIST_ENTRY \
-            AST_RWDLLIST_ENTRY \
-            AST_CLI_DEFINE \
-            AST_OPTIONAL_API \
-            AST_OPTIONAL_API_ATTR
+EXPAND_AS_DEFINED      = AST_INLINE_API \
+                         AST_DECLARE_STRING_FIELDS \
+                         AST_STRING_FIELD \
+                         AST_THREADSTORAGE \
+                         AST_THREADSTORAGE_CUSTOM \
+                         AST_MODULE_INFO \
+                         AST_MODULE_INFO_STANDARD \
+                         __AST_MUTEX_DEFINE \
+                         AST_MUTEX_DEFINE_STATIC \
+                         AST_MUTEX_DEFINE_STATIC_NOTRACKING \
+                         __AST_RWLOCK_DEFINE \
+                         AST_RWLOCK_DEFINE_STATIC \
+                         AST_LIST_HEAD \
+                         AST_RWLIST_HEAD \
+                         AST_LIST_HEAD_NOLOCK \
+                         AST_LIST_HEAD_STATIC \
+                         AST_RWLIST_HEAD_STATIC \
+                         AST_LIST_HEAD_NOLOCK_STATIC \
+                         AST_LIST_ENTRY \
+                         AST_RWLIST_ENTRY \
+                         __ASTOBJ_HASH \
+                         ASTOBJ_COMPONENTS_NOLOCK_FULL \
+                         ASTOBJ_COMPONENTS_NOLOCK \
+                         ASTOBJ_COMPONENTS_FULL \
+                         ASTOBJ_COMPONENTS \
+                         AST_IVR_DECLARE_MENU \
+                         AST_DECLARE_APP_ARGS \
+                         AST_DEFINE_APP_ARGS_TYPE \
+                         AST_APP_ARG \
+                         BEGIN_OPTIONS \
+                         END_OPTIONS \
+                         AST_APP_OPTIONS \
+                         AST_APP_OPTION \
+                         AST_APP_OPTION_ARG \
+                         AST_DLLIST_HEAD \
+                         AST_DLLIST_HEAD_STATIC \
+                         AST_DLLIST_HEAD_NOLOCK \
+                         AST_DLLIST_HEAD_NOLOCK_STATIC \
+                         AST_RWDLLIST_HEAD \
+                         AST_RWDLLIST_HEAD_STATIC \
+                         AST_DLLIST_ENTRY \
+                         AST_RWDLLIST_ENTRY \
+                         AST_CLI_DEFINE \
+                         AST_OPTIONAL_API \
+                         AST_OPTIONAL_API_ATTR
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
 # doxygen's preprocessor will remove all function-like macros that are alone
diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h
index 5b2612e44..e8d72582a 100644
--- a/include/asterisk/doxyref.h
+++ b/include/asterisk/doxyref.h
@@ -329,10 +329,6 @@
  */
 
 /*! 
- * \page Config_ast Asterisk.conf
- */
-
-/*! 
  * \page Config_mod Modules configuration
  * All res_ resource modules are loaded with globals on, which means
  * that non-static functions are callable from other modules.
@@ -350,14 +346,7 @@
  * \verbinclude features.conf.sample
  */
 
-/*! 
- * \page Config_followme Followme: An application for simple follow-me calls
- * \section followmeconf Followme.conf
- * - See app_followme.c
- * \verbinclude followme.conf.sample
- */
-
-/*! 
+/*!
  * \page Config_ext Extensions.conf - the Dial Plan
  * \section dialplan Extensions.conf 
  * \verbinclude extensions.conf.sample
@@ -640,7 +629,7 @@
  * repository on svn.digium.com
  */
 
-/*! 
+/*!
  * \page AstHTTP AMI over HTTP support
  * The http.c file includes support for manager transactions over
  * http.
@@ -662,6 +651,9 @@
  * Doxygen Groups
  */
 
+/*! \addtogroup configuration_file Configuration Files
+ */
+
 /*! 
  * \addtogroup cdr_drivers Module: CDR Drivers
  * \section CDR_generic Asterisk CDR Drivers
diff --git a/main/asterisk.c b/main/asterisk.c
index 4e3d24e61..f586a3764 100644
--- a/main/asterisk.c
+++ b/main/asterisk.c
@@ -28,8 +28,11 @@
  * examples, developer documentation, support information, and information
  * for upgrading.
  * 
- * 
- * 
+ * \section community Community
+ * Asterisk is a big project and has a busy community. Look at the
+ * resources for questions and stick around to help answer questions.
+ * \li \ref asterisk_community_resources
+ *
  * \par Developer Documentation for Asterisk
  *
  * This is the main developer documentation for Asterisk. It is
@@ -44,7 +47,7 @@
  * \par Additional documentation
  * \arg \ref Licensing
  * \arg \ref DevDoc
- * \arg \ref ConfigFiles
+ * \arg \ref configuration_file
  *
  * \section copyright Copyright and Author
  *
@@ -60,7 +63,69 @@
  * the project provides a web site, mailing lists, and IRC
  * channels for your use.
  *
- * \todo Add pages for mailinglists, IRC, etc...
+ */
+
+/*!
+ * \page asterisk_community_resources Asterisk Community Resources
+ * \par Websites
+ * \li http://www.asterisk.org Asterisk Homepage
+ * \li http://wiki.asterisk.org Asterisk Wiki
+ *
+ * \par Mailing Lists
+ * \par
+ * All lists: http://lists.digium.com/mailman/listinfo
+ * \li aadk-commits	SVN commits to the AADK repository
+ * \li asterisk-addons-commits	SVN commits to the Asterisk addons project
+ * \li asterisk-announce	[no description available]
+ * \li asterisk-biz	Commercial and Business-Oriented Asterisk Discussion
+ * \li Asterisk-BSD	Asterisk on BSD discussion
+ * \li asterisk-bugs	[no description available]
+ * \li asterisk-commits	SVN commits to the Asterisk project
+ * \li asterisk-dev	Asterisk Developers Mailing List
+ * \li asterisk-doc	Discussions regarding The Asterisk Documentation Project
+ * \li asterisk-embedded	Asterisk Embedded Development
+ * \li asterisk-gui	Asterisk GUI project discussion
+ * \li asterisk-gui-commits	SVN commits to the Asterisk-GUI project
+ * \li asterisk-ha-clustering	Asterisk High Availability and Clustering List - Non-Commercial Discussion
+ * \li Asterisk-i18n	Discussion of Asterisk internationalization
+ * \li asterisk-r2	[no description available]
+ * \li asterisk-scf-commits	Commits to the Asterisk SCF project code repositories
+ * \li asterisk-scf-committee	Asterisk SCF Steering Committee discussions
+ * \li asterisk-scf-dev	Asterisk SCF Developers Mailing List
+ * \li asterisk-scf-wiki-changes	Changes to the Asterisk SCF space on wiki.asterisk.org
+ * \li asterisk-security	Asterisk Security Discussion
+ * \li asterisk-speech-rec	Use of speech recognition in Asterisk
+ * \li asterisk-ss7	[no description available]
+ * \li asterisk-users	Asterisk Users Mailing List - Non-Commercial Discussion
+ * \li asterisk-video	Development discussion of video media support in Asterisk
+ * \li asterisk-wiki-changes	Changes to the Asterisk space on wiki.asterisk.org
+ * \li asterisknow	AsteriskNOW Discussion
+ * \li dahdi-commits	SVN commits to the DAHDI project
+ * \li digium-announce	Digium Product Announcements
+ * \li Dundi	Distributed Universal Number Discovery
+ * \li libiax2-commits	SVN commits to the libiax2 project
+ * \li libpri-commits	SVN commits to the libpri project
+ * \li libss7-commits	SVN commits to the libss7 project
+ * \li svn-commits	SVN commits to the Digium repositories
+ * \li Test-results	Results from automated testing
+ * \li thirdparty-commits	SVN commits to the Digium third-party software repository
+ * \li zaptel-commits	SVN commits to the Zaptel project
+ *
+ * \par Forums
+ * \li Forums are located at http://forums.asterisk.org/
+ *
+ * \par IRC
+ * \par
+ * Use http://www.freenode.net IRC server to connect with Asterisk
+ * developers and users in realtime.
+ * 
+ * \li \verbatim #asterisk \endverbatim Asterisk Users Room
+ * \li \verbatim #asterisk-dev \endverbatim Asterisk Developers Room
+ *
+ * \par More
+ * \par
+ * If you would like to add a resource to this list please create an issue
+ * on the issue tracker with a patch.
  */
 
 /*! \file
@@ -68,6 +133,15 @@
  *	Implementation of PBX core functions and CLI interface.
  */
 
+/*!
+ * \li The Asterisk core uses the configuration file \ref asterisk.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page asterisk.conf asterisk.conf
+ * \verbinclude asterisk.conf.sample
+ */
+
 /*** MODULEINFO
 	<support_level>core</support_level>
  ***/
diff --git a/main/http.c b/main/http.c
index de8a57388..b940ae17e 100644
--- a/main/http.c
+++ b/main/http.c
@@ -30,6 +30,15 @@
  * \ref AstHTTP - AMI over the http protocol
  */
 
+/*!
+ * \li The core module http uses the configuration file \ref http.conf
+ * \addtogroup configuration_file
+ */
+
+/*! \page http.conf http.conf
+ * \verbinclude http.conf.sample
+ */
+
 /*** MODULEINFO
 	<support_level>core</support_level>
  ***/