Add some additional Asterisk project developer documentation.

After the nightly update of the documentation on asterisk.org, I'll post 
an update to asterisk-dev with a pointer to the changes.  This covers some
release branch and commit policy information.  None of this should be a
surprise, since it's just documenting what we have already been doing.


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

contrib/asterisk-ng-doxygen

@@ -178,6 +178,7 @@ TAB_SIZE               = 3
 # 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."
 
 # 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. 

include/asterisk/doxyref.h

@@ -1,9 +1,7 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 1999 - 2005, Digium, Inc.
+ * Copyright (C) 1999 - 2008, Digium, Inc.
- *
- * Mark Spencer <markster@digium.com>
  *
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
@@ -16,55 +14,330 @@
  * at the top of the source tree.
  */
 
-/*! \file 
+/*! 
+ * \file 
  * \brief This file generates Doxygen pages from files in the /doc
- directory of the Asterisk source code tree 
+ *        directory of the Asterisk source code tree 
  */
 
-/* The following is for Doxygen Developer's documentation generated
+/* 
+ * The following is for Doxygen Developer's documentation generated
  * by running "make progdocs" with doxygen installed on your
  * system.
  */
-/*! \page DevDoc Asterisk Developer's Documentation - appendices
+
- *  \arg \ref CodeGuide : The must-read document for all developer's
+/*! 
+ * \page DevDoc Asterisk Developer's Documentation - Appendices
+ *
+ * \section devpolicy Development and Release Policies
+ * \arg \ref CodeGuide : The must-read document for all developers
+ * \arg \ref ReleaseStatus : The current support level for various Asterisk releases
+ * \arg \ref ReleasePolicies : Asterisk Release and Commit Policies
+ * \arg \ref AstCREDITS : A Thank You to contributors (unfortunately out of date)
+ *
+ * \section apisandinterfaces Asterisk APIs and Interfaces
  * \arg \ref AstAPI
  * \arg \ref Def_Channel : What's a channel, anyway?
  * \arg \ref channel_drivers : Existing channel drivers
- *  \arg \ref AstDebug : Hints on debugging
  * \arg \ref AstAMI : The Call management socket API
  * \arg \ref AstARA : A generic data storage and retrieval API for Asterisk
  * \arg \ref AstDUNDi : A way to find phone services dynamically by using the DUNDi protocol
  * \arg \ref AJI_intro : The Asterisk Jabber Interface
  * \arg \ref AstCDR
- *  \arg \ref AstREADME
  * \arg \ref AstVar
  * \arg \ref AstVideo
  * \arg \ref AstENUM : The IETF way to redirect from phone numbers to VoIP calls
  * \arg \ref AstHTTP
  * \arg \ref AstSpeech
+ *
+ * \section debugconfig Debugging and Configuration References
+ * \arg \ref AstREADME : General Administrator README file
+ * \arg \ref AstDebug : Hints on debugging
+ * \arg \ref extref 
  * \arg \ref ConfigFiles
  * \arg \ref SoundFiles included in the Asterisk distribution
- *  \arg \ref AstCREDITS : A Thank You to contributors
+ *
- *  \arg \ref extref 
- \n\n
  * \section weblinks Web sites
  * \arg \b Main:  Asterisk Developer's website http://www.asterisk.org/developers/
- * \arg \b Bugs: The Issue tracker http://bugs.digium.com
+ * \arg \b Bugs: The Issue Tracker http://bugs.digium.com
- * \arg \b Lists: List server http://lists.digium.com
+ * \arg \b Lists: List Server http://lists.digium.com
  * \arg \b Wiki: The Asterisk Wiki 	http://www.voip-info.org
  * \arg \b Docs: The Asterisk Documentation Project http://www.asteriskdocs.org
- * \arg \b Digium: The Asterisk company http://www.digium.com
+ * \arg \b Digium: The Asterisk Company http://www.digium.com
- *
  */
 
-/*! \page CodeGuide Coding Guidelines
+/*!
+ * \page ReleaseStatus Asterisk Release Status
+ *
+ * @AsteriskTrunkWarning
+ *
+ * \section warranty Warranty
+ * The following warranty applies to all open source releases of Asterisk:
+ *
+ * NO WARRANTY
+ *
+ * BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+ * FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+ * OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+ * PROVIDE THE PROGRAM \"AS IS\" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+ * OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+ * TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+ * PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+ * REPAIR OR CORRECTION.
+
+ * IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+ * WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+ * REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+ * INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+ * OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+ * TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+ * YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+ * PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGES.
+ *
+ * \section releasestatustypes Release Status Types
+ *
+ * Release management is a essentially an agreement between the development
+ * community and the user community on what kind of updates can be expected
+ * for Asterisk releases, and what types of changes these updates will contain.
+ * Once these policies are established, the development community works very
+ * hard to adhere to them.  However, the development community does reserve
+ * the right to make exceptions to these rules for special cases as the need
+ * arises.
+ *
+ * Asterisk releases are in various states of maintenance.  The states are
+ * defined here:
+ *
+ * \arg <b>None</b> - This release series is receiving no updates whatsoever.
+ * \arg <b>Security-Only</b> - This release series is receiving updates, but
+ *      only to address security issues.  Security issues found and fixed in
+ *      this release series will be accompanied by a published security advisory
+ *      from the Asterisk project.
+ * \arg <b>Full-Support</b> - This release series is receiving updates for all
+ *      types of bugs.
+ * \arg <b>Full-Development</b> - Changes in this part of Asterisk include bug
+ *      fixes, as well as new features and architectural improvements.
+ *
+ * \section AsteriskReleases Asterisk Maintenance Levels
+ *
+ * \htmlonly
+ * <table border="1">
+ *  <tr>
+ *   <td><b>Name</b></td>
+ *   <td><b>SVN Branch</b></td>
+ *   <td><b>Status</b></td>
+ *   <td><b>Notes</b></td>
+ *  </tr>
+ *  <tr>
+ *   <td>Asterisk 1.0</td>
+ *   <td>/branches/1.0</td>
+ *   <td>None</td>
+ *  </tr>
+ *  <tr>
+ *   <td>Asterisk 1.2</td>
+ *   <td>/branches/1.2</td>
+ *   <td>Security-Only</td>
+ *  </tr>
+ *  <tr>
+ *   <td>Asterisk 1.4</td>
+ *   <td>/branches/1.4</td>
+ *   <td>Full-Support</td>
+ *  </tr>
+ *  <tr>
+ *   <td>Asterisk 1.6.0</td>
+ *   <td>/branches/1.6.0</td>
+ *   <td>Full-Support</td>
+ *  </tr>
+ *  <tr>
+ *   <td>Asterisk 1.6.1</td>
+ *   <td>/branches/1.6.1</td>
+ *   <td>Full-Support</td>
+ *   <td>Still in beta</td>
+ *  </tr>
+ *  <tr>
+ *   <td>Asterisk trunk</td>
+ *   <td>/trunk</td>
+ *   <td>Full-Development</td>
+ *   <td>No releases are made directly from trunk.</td>
+ *  </tr>
+ * </table>
+ * \endhtmlonly
+ *
+ * For more information on how and when Asterisk releases are made, see the
+ * release policies page:
+ * \arg \ref ReleasePolicies
+ */
+
+/*!
+ * \page ReleasePolicies Asterisk Release and Commit Policies
+ *
+ * \AsteriskTrunkWarning
+ *
+ * \section releasestatus Asterisk Release Status
+ *
+ * For more information on the current status of each Asterisk release series,
+ * please see the Asterisk Release Status page:
+ *
+ * \arg \ref ReleaseStatus
+ *
+ * <hr/>
+ *
+ * \section commitmonitoring Commit Monitoring
+ *
+ * To monitor commits to Asterisk and related projects, visit 
+ * <a href="http://lists.digium.com/">http://lists.digium.com</a>.  The Digium
+ * mailing list server hosts a number of mailing lists for commits.
+ *
+ * <hr/>
+ *
+ * \section ast10policy Asterisk 1.0
+ *
+ * \subsection svnbranch SVN Branch
+ *
+ * \arg /branches/1.0
+ *
+ * \subsection ast10releases Release and Commit Policy
+ * No more releases of Asterisk 1.0 will be made for any reason.
+ *
+ * No commits should be made to the Asterisk 1.0 branch.
+ * 
+ * <hr/>
+ *
+ * \section ast12policy Asterisk 1.2
+ *
+ * \subsection svnbranch SVN Branch
+ *
+ * \arg /branches/1.2
+ *
+ * \subsection ast12releases Release and Commit Policy
+ *
+ * There will be no more scheduled releases of Asterisk 1.2.
+ * 
+ * Commits to the Asterisk 1.2 branch should only address security issues or
+ * regressions introduced by previous security fixes.  For a security issue, the
+ * commit should be accompanied by an 
+ * <a href="http://downloads.digium.com/pub/security/">Asterisk Security Advisory</a>
+ * and an immediate release.  When a commit goes in to fix a regression, the previous
+ * security advisory that is related to the change that introduced the bug should get
+ * updated to indicate that there is an updated version of the fix.  A release should
+ * be made immediately for these regression fixes, as well.
+ *
+ * <hr/>
+ *
+ * \section ast14policy Asterisk 1.4
+ *
+ * \subsection svnbranch SVN Branch
+ *
+ * \arg /branches/1.4
+ *
+ * \subsection ast14releases Release and Commit Policy
+ *
+ * Asterisk 1.4 is receiving regular bug fix release updates.  An attempt is made to
+ * make releases of every four to six weeks.  Since this release series is receiving
+ * changes for all types of bugs, the number of changes in a single release can be
+ * significant.  1.4.X releases go through a release candidate testing cycle to help
+ * catch any regressions that may have been introduced.
+ *
+ * Commits to Asterisk 1.4 must be to address bugs only.  No new features should be
+ * introduced into Asterisk 1.4 to reduce the number of changes to this established
+ * release series.  The only exceptions to this rule are for cases where something
+ * that may be considered a feature is needed to address a bug or security issue.
+ *
+ * <hr/>
+ *
+ * \section ast16policy Asterisk 1.6
+ *
+ * \subsection svnbranch SVN Branch
+ *
+ * \arg /branches/1.6.*
+ *
+ * \subsection ast16releases Release and Commit Policy
+ *
+ * Asterisk 1.6 is managed in a different way than previous Asterisk release series.
+ * From a high level, it was inspired by the release model used for Linux 2.6.
+ * The intended time frame for 1.6.X releases is every 2 or 3 months.  Each 1.6.X
+ * release gets its own branch.  The 1.6.X branches are branches off of trunk.
+ * Once the branch is created, it only receives bug fixes.  Each 1.6.X release goes
+ * through a beta and release candidate testing cycle.
+ *
+ * After a 1.6.X release is published, it will be maintained until 1.6.[X + 3] is
+ * released.  While a 1.6.X release branch is still maintained, it will receive only
+ * bug fixes.  Periodic maintenance releases will be made and labeled as 1.6.X.Y.
+ * 1.6.X.Y releases should go through a release candidate test cycle before being
+ * published.
+ *
+ * For now, all previous 1.6 release will be maintained for security issues.  Once
+ * we have more 1.6 releases to deal with, this part of the policy will likely change.
+ * 
+ * For some history on the motivations for Asterisk 1.6 release management, see the
+ * first two sections of this
+ * <a href="http://lists.digium.com/pipermail/asterisk-dev/2007-October/030083.html">mailing list post</a>.
+ *
+ * <hr/>
+ *
+ * \section asttrunk Asterisk Trunk
+ *
+ * \subsection svnbranch SVN Branch
+ *
+ * \arg /trunk
+ *
+ * \subsection asttrunkpolicy Release and Commit Policy
+ *
+ * No releases are ever made directly from Asterisk trunk.
+ *
+ * Asterisk trunk is used as the main development area for upcoming Asterisk 1.6 
+ * releases.  Commits to Asterisk trunk are not limited.  They can be bug fixes,
+ * new features, and architectural improvements.  However, for larger sets
+ * of changes, developers should work with the Asterisk project leaders to
+ * schedule them for inclusion.  Care is taken not to include too many invasive
+ * sets of changes for each new Asterisk 1.6 release.
+ *
+ * No changes should go into Asterisk trunk that are not ready to go into a
+ * release.  While the upcoming release will go through a beta and release
+ * candidate test cycle, code should not be in trunk until the code has been
+ * tested and reviewed such that there is reasonable belief that the code
+ * is ready to go.
+ *
+ * <hr/>
+ *
+ * \section astteam Asterisk Team Branches
+ *
+ * \subsection svnbranch SVN Branch
+ *
+ * \arg /team/&lt;developername&gt;
+ *
+ * \subsection astteampolicy Release and Commit Policy
+ *
+ * The Asterisk subversion repository has a special directory called "team"
+ * where developers can make their own personal development branches.  This is
+ * where new features, bug fixes, and architectural improvements are developed
+ * while they are in progress.
+ *
+ * Just about anything goes as far as commits to this area goes.  However,
+ * developers should keep in mind that anything committed here, as well as
+ * anywhere else on Digium's SVN server, falls under the contributor license
+ * agreement.
+ *
+ * In addition to each developer having their own space for working on projects,
+ * there is also a team/group folder where group development efforts take place.
+ *
+ * Finally, in each developer folder, there is a folder called "private".  This
+ * is where developers can create branches for working on things that they are
+ * not ready for the whole world to see.
+ */
+
+/*! 
+ * \page CodeGuide Coding Guidelines
+ * \AsteriskTrunkWarning
  * \section Coding Guidelines
  * This file is in the /doc directory in your Asterisk source tree.
  * Make sure to stay up to date with the latest guidelines.
  * \verbinclude CODING-GUIDELINES
  */
 
-/*! \page AstAPI Asterisk API
+/*! 
+ * \page AstAPI Asterisk API
  * \section Asteriskapi Asterisk API
  * Some generic documents on the Asterisk architecture
  *
@@ -78,29 +351,34 @@
  * \arg See \ref Def_Channel
  */
 
-/*! \page AstDebug Debugging
+/*! 
+ * \page AstDebug Debugging
  * \section debug Debugging
  * \verbinclude backtrace.txt
  */
 
-/*! \page AstSpeech The Generic Speech Recognition API
+/*!
+ * \page AstSpeech The Generic Speech Recognition API
  * \section debug The Generic Speech Recognition API
  * \verbinclude speechrec.txt
  */
 
-/*! \page DataStores Channel Data Stores
+/*! 
+ * \page DataStores Channel Data Stores
  * \section debug Channel Data Stores
  * \verbinclude datastores.txt
  */
 
-/*! \page AstAMI AMI - The Manager Interface
+/*! 
+ * \page AstAMI AMI - The Manager Interface
  * \section ami AMI - The manager Interface
  * \arg \link Config_ami Configuration file \endlink
  * \arg \ref manager.c
  * \verbinclude manager.txt
  */
 
-/*!  \page AstARA ARA - The Asterisk Realtime Interface
+/*!
+ * \page AstARA ARA - The Asterisk Realtime Interface
  * \section realtime ARA - a generic API to storage and retrieval
  * Implemented in \ref config.c 
  * Implemented in \ref pbx_realtime.c 
@@ -108,18 +386,26 @@
  * \verbinclude extconfig.txt
  */
 
-/*!  \page AstDUNDi DUNDi
+/*! 
-DUNDi is a peer-to-peer system for locating Internet gateways to telephony services. Unlike traditional centralized services (such as the remarkably simple and concise ENUM standard), DUNDi is fully-distributed with no centralized authority whatsoever.
+ * \page AstDUNDi DUNDi
-
+ *
-DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it publishes routes which are in turn accessed via industry standard protocols such as IAX, SIP and H.323. 
+ * DUNDi is a peer-to-peer system for locating Internet gateways to telephony 
-
+ * services. Unlike traditional centralized services (such as the remarkably 
-	\par References
+ * simple and concise ENUM standard), DUNDi is fully-distributed with no 
- 	\arg DUNDi is documented at http://www.dundi.com
+ * centralized authority whatsoever.
-  	\arg Implemented in \ref pbx_dundi.c and \ref dundi-parser.c
+ *
- 	\arg Configuration in \link Config_dun dundi.conf \endlink
+ * DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, 
+ * it publishes routes which are in turn accessed via industry standard 
+ * protocols such as IAX, SIP and H.323. 
+ *
+ * \par References
+ * \arg DUNDi is documented at http://www.dundi.com
+ * \arg Implemented in \ref pbx_dundi.c and \ref dundi-parser.c
+ * \arg Configuration in \link Config_dun dundi.conf \endlink
  */
 
-/*! \page AstCDR CDR - Call Data Records and billing
+/*! 
+ * \page AstCDR CDR - Call Data Records and billing
  * \section cdr Call Data Records
  * \par See also
  * \arg \ref cdr.c
@@ -129,20 +415,24 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude cdrdriver.txt
  */
 
-/*! \page AstREADME README - the general administrator introduction
+/*! 
+ * \page AstREADME README
  * \verbinclude README
  */
  
-/*! \page AstCREDITS CREDITS
+/*! 
+ * \page AstCREDITS CREDITS
  * \verbinclude CREDITS
  */
 
-/*! \page AstVideo Video support in Asterisk
+/*! 
+ * \page AstVideo Video support in Asterisk
  * \section sectAstVideo Video support in Asterisk
  * \verbinclude video.txt
  */
 
-/*! \page AstVar Globally predefined channel variables
+/*! 
+ * \page AstVar Globally predefined channel variables
  * \section globchan Globally predefined channel variables
  *
  * More and more of these variables are being replaced by dialplan functions.
@@ -154,10 +444,10 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * - \ref AstChanVar
  *
  *  \verbinclude channelvariables.tex
-
  */
 
-/*! \page AstChanVar Asterisk Dialplan Variables
+/*! 
+ * \page AstChanVar Asterisk Dialplan Variables
  *	Asterisk Dialplan variables are divided into three groups:
  *	- Predefined global variables, handled by the PBX core
  *	- Global variables, that exist for the duration of the pbx execution
@@ -201,11 +491,10 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  *
  * The variables is a linked list stored in the channel data structure
  * with the list starting at varshead in struct ast_channel
- * 
- *
  */
 
-/*! \page AstENUM ENUM
+/*! 
+ * \page AstENUM ENUM
  * \section enumreadme ENUM
  * \arg Configuration: \ref Config_enum
  * \arg \ref enum.c
@@ -214,7 +503,8 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude enum.txt
  */
 
-/*! \page ConfigFiles Configuration files
+/*! 
+ * \page ConfigFiles Configuration files
  * \section config Main configuration files
  * \arg \link Config_ast asterisk.conf - the main configuration file \endlink
  * \arg \link Config_ext extensions.conf - The Dial Plan \endlink
@@ -256,10 +546,13 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \arg \link res_config_sqlite SQLite Resource driver configuration \endlink
  */
 
-/*! \page Config_ast Asterisk.conf
+/*! 
+ * \page Config_ast Asterisk.conf
  * \verbinclude asterisk-conf.txt
  */
-/*! \page Config_mod Modules configuration
+
+/*! 
+ * \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.
  *
@@ -268,25 +561,29 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude modules.conf.sample
  */
 
-/*! \page Config_fea Call features configuration
+/*! 
+ * \page Config_fea Call features configuration
  * \par See also
  * \arg \ref res_features.c : Call feature implementation
  * \section featconf features.conf
  * \verbinclude features.conf.sample
  */
 
-/*! \page Config_followme Followme: An application for simple follow-me calls
+/*! 
+ * \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
+/*! 
+ * \page Config_ext Extensions.conf - the Dial Plan
  * \section dialplan Extensions.conf 
  * \verbinclude extensions.conf.sample
  */
 
-/*! \page Config_iax IAX2 configuration
+/*! 
+ * \page Config_iax IAX2 configuration
  * IAX2 is implemented in \ref chan_iax2.c
  * \arg \link Config_iax iax.conf Configuration file example \endlink
  * \section iaxreadme IAX readme file
@@ -297,13 +594,15 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude jitterbuffer.txt
  */
 
-/*! \page Config_iax IAX configuration
+/*! 
+ * \page Config_iax IAX configuration
  * \arg Implemented in \ref chan_iax2.c
  * \section iaxconf iax.conf
  * \verbinclude iax.conf.sample
  */
 
-/*! \page Config_sip SIP configuration
+/*! 
+ * \page Config_sip SIP configuration
  * Also see \ref Config_rtp RTP configuration
  * \arg Implemented in \ref chan_sip.c
  * \section sipconf sip.conf
@@ -312,20 +611,23 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \arg \b Back \ref chanconf
  */
 
-/*! \page Config_mgcp MGCP configuration
+/*! 
+ * \page Config_mgcp MGCP configuration
  * Also see \ref Config_rtp RTP configuration
  * \arg Implemented in \ref chan_mgcp.c
  * \section mgcpconf mgcp.conf
  * \verbinclude mgcp.conf.sample
  */
 
-/*! \page README_misdn MISDN documentation
+/*! 
+ * \page README_misdn MISDN documentation
  * \arg See \ref Config_misdn
  * \section mISDN configuration
  * \verbinclude misdn.txt
  */
 
-/*! \page Config_misdn MISDN configuration
+/*! 
+ * \page Config_misdn MISDN configuration
  * \arg Implemented in \ref chan_misdn.c
  * \arg \ref README_misdn
  * \arg See the mISDN home page: http://www.isdn4linux.de/mISDN/
@@ -333,19 +635,22 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude misdn.conf.sample
  */
 
-/*! \page Config_vm VoiceMail configuration
+/*! 
+ * \page Config_vm VoiceMail configuration
  * \section vmconf voicemail.conf
  * \arg Implemented in \ref app_voicemail.c
  * \verbinclude voicemail.conf.sample
  */
 
-/*! \page Config_dahdi DAHDI configuration
+/*! 
+ * \page Config_dahdi DAHDI configuration
  * \section dahdiconf dahdi.conf
  * \arg Implemented in \ref chan_dahdi.c
  * \verbinclude dahdi.conf.sample
  */
 
-/*! \page Config_h323 H.323 channel driver information
+/*! 
+ * \page Config_h323 H.323 channel driver information
  * This is the configuration of the H.323 channel driver within the Asterisk
  * distribution. There's another one, called OH323, in asterisk-addons
  * \arg Implemented in \ref chan_h323.c
@@ -353,53 +658,61 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \ref chan_h323.c
  */
 
-/*! \page Config_oss OSS configuration
+/*! 
+ * \page Config_oss OSS configuration
  * \section ossconf oss.conf
  * \arg Implemented in \ref chan_oss.c
  * \verbinclude oss.conf.sample
  */
 
-/*! \page Config_alsa ALSA configuration
+/*! 
+ * \page Config_alsa ALSA configuration
  * \section alsaconf alsa.conf
  * \arg Implemented in \ref chan_alsa.c
  * \verbinclude alsa.conf.sample
  */
 
-/*! \page Config_agent Agent configuration
+/*! 
+ * \page Config_agent Agent configuration
  * \section agentconf agents.conf
  * The agent channel is a proxy channel for queues
  * \arg Implemented in \ref chan_agent.c
  * \verbinclude agents.conf.sample
  */
 
-/*! \page Config_rtp RTP configuration
+/*! 
+ * \page Config_rtp RTP configuration
  * \arg Implemented in \ref rtp.c
  * Used in \ref chan_sip.c and \ref chan_mgcp.c (and various H.323 channels)
  * \section rtpconf rtp.conf
  * \verbinclude rtp.conf.sample
  */
 
-/*! \page Config_dun DUNDi Configuration
+/*! 
+ * \page Config_dun DUNDi Configuration
  * \arg See also \ref AstDUNDi
  * \section dundiconf dundi.conf
  * \verbinclude dundi.conf.sample
  */
 
-/*! \page Config_enum ENUM Configuration
+/*! 
+ * \page Config_enum ENUM Configuration
  * \section enumconf enum.conf
  * \arg See also \ref enumreadme
  * \arg Implemented in \ref func_enum.c and \ref enum.c
  * \verbinclude enum.conf.sample
  */
 
-/*! \page cdr_custom Custom CDR Configuration
+/*! 
+ * \page cdr_custom Custom CDR Configuration
  * \par See also 
  * \arg \ref cdrconf
  * \arg \ref cdr_custom.c
  * \verbinclude cdr_custom.conf.sample
  */
 
-/*! \page cdr_ami Manager CDR driver configuration
+/*! 
+ * \page cdr_ami Manager CDR driver configuration
  * \par See also 
  * \arg \ref cdrconf
  * \arg \ref AstAMI
@@ -407,7 +720,8 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude cdr_manager.conf.sample
  */
 
-/*! \page cdr_odbc ODBC CDR driver configuration
+/*! 
+ * \page cdr_odbc ODBC CDR driver configuration
  * \arg See also \ref cdrconf
  * \arg \ref cdr_odbc.c
  * \verbinclude cdr_odbc.conf.sample
@@ -415,7 +729,8 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \arg http://www.unixodbc.org
  */
 
-/*! \page cdr_pgsql PostgreSQL CDR driver configuration
+/*! 
+ * \page cdr_pgsql PostgreSQL CDR driver configuration
  * \arg See also \ref cdrconf
  * \arg \ref cdr_pgsql.c
  * See also:
@@ -423,21 +738,24 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude cdr_pgsql.conf.sample
  */
 
-/*! \page cdr_sqlite SQLite CDR driver configuration
+/*! 
+ * \page cdr_sqlite SQLite CDR driver configuration
  * \arg See also \ref cdrconf
  * \arg \ref cdr_sqlite.c
  * See also:
  * \arg http://www.sqlite.org
  */
 
-/*! \page cdr_tds FreeTDS CDR driver configuration
+/*! 
+ * \page cdr_tds FreeTDS CDR driver configuration
  * \arg See also \ref cdrconf
  * See also:
  * \arg http://www.freetds.org
  * \verbinclude cdr_tds.conf.sample
  */
 
-/*! \page Config_cdr CDR configuration
+/*! 
+ * \page Config_cdr CDR configuration
  * \par See also
  * \arg \ref cdr_drivers
  * \arg \link Config_cdr CDR configuration  \endlink  
@@ -450,47 +768,55 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude cdr.conf.sample
  */
 
-/*! \page Config_moh Music on Hold Configuration
+/*! 
+ * \page Config_moh Music on Hold Configuration
  * \arg Implemented in \ref res_musiconhold.c
  * \section mohconf musiconhold.conf
  * \verbinclude musiconhold.conf.sample
  */
 
-/*! \page Config_adsi ADSI Configuration
+/*! 
+ * \page Config_adsi ADSI Configuration
  * \section adsiconf adsi.conf
  * \verbinclude adsi.conf.sample
  */
 
-/*! \page Config_codec CODEC Configuration
+/*! 
+ * \page Config_codec CODEC Configuration
  * \section codecsconf codecs.conf
  * \verbinclude codecs.conf.sample
  */
 
-/*! \page Config_ara REALTIME Configuration
+/*! 
+ * \page Config_ara REALTIME Configuration
  * \arg See also: \arg \link AstARA \endlink
  * \section extconf extconfig.conf
  * \verbinclude extconfig.conf.sample
  */
 
-/*! \page Config_ami AMI configuration
+/*! 
+ * \page Config_ami AMI configuration
  * \arg See also: \arg \link AstAMI \endlink
  * \section amiconf manager.conf
  * \verbinclude manager.conf.sample
  */
 
-/*! \page Config_qu ACD - Queue system configuration
+/*! 
+ * \page Config_qu ACD - Queue system configuration
  * \arg Implemented in \ref app_queue.c
  * \section quconf queues.conf
  * \verbinclude queues.conf.sample
  */
 
-/*! \page Config_mm Meetme - The conference bridge configuration
+/*! 
+ * \page Config_mm Meetme - The conference bridge configuration
  * \arg Implemented in \ref app_meetme.c
  * \section mmconf meetme.conf
  * \verbinclude meetme.conf.sample
  */
 
-/*! \page SoundFiles Sound files
+/*! 
+ * \page SoundFiles Sound files
  * \section SecSound Asterisk Sound files
  * Asterisk includes a large number of sound files. Many of these
  * are used by applications and demo scripts within asterisk.
@@ -499,29 +825,35 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * repository on svn.digium.com
  */
 
-/*! \addtogroup cdr_drivers Module: CDR Drivers
+/*! 
+ * \addtogroup cdr_drivers Module: CDR Drivers
  * \section CDR_generic Asterisk CDR Drivers
- *  \brief CDR drivers are loaded dynamically, each loaded CDR driver produce a billing record for each call.
+ * \brief CDR drivers are loaded dynamically, each loaded CDR driver produce 
+ *        a billing record for each call.
  * \arg \ref Config_mod "Modules Configuration"
  * \arg \ref Config_cdr "CDR Configuration"
  */
 
 
-/*! \addtogroup channel_drivers Module: Asterisk Channel Drivers
+/*! 
+ * \addtogroup channel_drivers Module: Asterisk Channel Drivers
  * \section channel_generic Asterisk Channel Drivers
  * \brief Channel drivers are loaded dynamically. 
  * \arg \ref Config_mod "Modules Configuration"
  */
 
-/*! \addtogroup applications Module: Dial plan applications
+/*! 
+ * \addtogroup applications Module: Dial plan applications
  * \section app_generic Asterisk Dial Plan Applications
- *  \brief Applications support the dialplan. They register dynamically with \see ast_register_application() and unregister with \see ast_unregister_application()
+ * \brief Applications support the dialplan. They register dynamically with 
+ *        \see ast_register_application() and unregister with 
+ *        \see ast_unregister_application()
  * \par See also
  * \arg \ref functions
- *  
  */
 
-/*! \addtogroup functions Module: Dial plan functions
+/*! 
+ * \addtogroup functions Module: Dial plan functions
  * \section func_generic Asterisk Dial Plan Functions
  * \brief Functions support the dialplan.  They do not change any property of a channel
  *        or touch a channel in any way.
@@ -530,29 +862,32 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  *  
  */
 
-/*! \addtogroup codecs Module: Codecs
+/*! 
+ * \addtogroup codecs Module: Codecs
  * \section codec_generic Asterisk Codec Modules
  * Codecs are referenced in configuration files by name 
  * \par See also 
  * \arg \ref formats 
- *
  */
 
-/*! \addtogroup formats Module: Media File Formats 
+/*! 
+ * \addtogroup formats Module: Media File Formats 
  * \section codec_generic Asterisk Format drivers
  * Formats are modules that read or write media files to disk.
  * \par See also
  * \arg \ref codecs 
  */
 
-/*! \page AstHTTP AMI over HTTP support
+/*! 
+ * \page AstHTTP AMI over HTTP support
  * The http.c file includes support for manager transactions over
  * http.
  * \section ami AMI - The manager Interface
  * \arg \link Config_ami Configuration file \endlink
  */
 
-/*! \page res_config_sqlite SQLite Resource driver configuration
+/*! 
+ * \page res_config_sqlite SQLite Resource driver configuration
  * \arg Implemented in \ref res_config_sqlite.c
  * \arg Configuration file:
  * \verbinclude res_config_sqlite.conf

main/asterisk.c

@@ -22,17 +22,24 @@
  * \mainpage Asterisk -- An Open Source Telephony Toolkit
  *
  * \par Developer Documentation for Asterisk
+ *
  * This is the main developer documentation for Asterisk. It is 
- * generated by running "make progdocs".
+ * generated by running "make progdocs" from the Asterisk source tree.  
+ *
+ * In addition to the information available on the Asterisk source code, 
+ * please see the appendices for information on coding guidelines, 
+ * release management, commit policies, and more.
+ *
  * \par Additional documentation
  * \arg \ref Licensing
  * \arg \ref DevDoc 
  * \arg \ref ConfigFiles
  *
- * \section copyright Copyright and author
+ * \section copyright Copyright and Author
  *
  * Copyright (C) 1999 - 2008, Digium, Inc.
- * Asterisk is a trademark registered by Digium, Inc.
+ * Asterisk is a <a href="http://www.digium.com/en/company/view-policy.php?id=Trademark-Policy">registered trademark</a>
+ * of <a href="http://www.digium.com">Digium, Inc</a>.
  *
  * \author Mark Spencer <markster@digium.com>
  * Also see \ref AstCREDITS
@@ -40,9 +47,8 @@
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
  * any of the maintainers of this project for assistance;
- * the project provides a web site, mailing lists and IRC
+ * the project provides a web site, mailing lists, and IRC
  * channels for your use.
- *
  */
 
 /*! \file