issue #5605

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

ChangeLog

@@ -4,6 +4,7 @@
 	* channels/chan_iax2.c: Use an enum to define iax peer/user flags as well as the pvt structure state.  Use the ast_flags macros for checking or setting the state.
 	* sounds.txt: Add missing words from the description of the vm-opts prompt
 	* apps/app_externalivr.c: Add a space that fixes building on older versions of gcc
+	* many files: Add doxygen updates to categorize modules into groups. Convert a lot of comments over to doxygen style. Add some text giving a basic overview of channels.
 
 2005-11-05  Kevin P. Fleming  <kpfleming@digium.com>
 

apps/app_adsiprog.c

@@ -19,6 +19,7 @@
 /*! \file
  * \brief Program Asterisk ADSI Scripts into phone
  * 
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_alarmreceiver.c

@@ -18,6 +18,7 @@
 
 /*! \file
  * \brief Central Station Alarm receiver for Ademco Contact ID  
+ * \author Steve Rodgers <hwstar@rodgers.sdcoxmail.com>
  * 
  * *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING *** 
  *
@@ -25,6 +26,7 @@
  *
  * *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***
  *
+ * \ingroup applications
  */ 
  
 #include <string.h>

apps/app_authenticate.c

@@ -19,6 +19,7 @@
 /*! \file
  * \brief Execute arbitrary authenticate commands
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_cdr.c

@@ -19,6 +19,7 @@
 /*! \file
  * \brief Applications connected with CDR engine
  *
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_chanisavail.c

@@ -1,25 +1,26 @@
 /*
- * Asterisk -- An open source telephony toolkit.
- *
- * Copyright (C) 1999 - 2005, Digium, Inc.
- *
- * Mark Spencer <markster@digium.com>
- * James Golovich <james@gnuinter.net>
- *
- * 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
- * channels for your use.
- *
- * This program is free software, distributed under the terms of
- * the GNU General Public License Version 2. See the LICENSE file
- * at the top of the source tree.
- */
+* Asterisk -- An open source telephony toolkit.
+*
+* Copyright (C) 1999 - 2005, Digium, Inc.
+*
+* Mark Spencer <markster@digium.com>
+* James Golovich <james@gnuinter.net>
+*
+* 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
+* channels for your use.
+*
+* This program is free software, distributed under the terms of
+* the GNU General Public License Version 2. See the LICENSE file
+* at the top of the source tree.
+*/
 
 /*! \file
- * \brief Check if Channel is Available
- * 
+* \brief Check if Channel is Available
+* 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_chanspy.c

@@ -19,6 +19,7 @@
 /*! \file
  * \brief ChanSpy: Listen in on any channel.
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_controlplayback.c

@@ -19,6 +19,7 @@
 /*! \file
  * \brief Trivial application to control playback of a sound file
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_curl.c

@@ -20,6 +20,7 @@
 /*! \file
  * \brief Curl - App to load a URL
  * 
+ * \ingroup applications
  */
  
 #include <stdlib.h>

apps/app_cut.c

@@ -18,6 +18,7 @@
 /*! \file
  * \brief Cut application
  *
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_datetime.c

@@ -19,6 +19,7 @@
 /*! \file
  * \brief Time of day - Report the time of day
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_db.c

@@ -22,6 +22,7 @@
  *
  * \brief Database access functions
  *
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_dial.c

@@ -20,6 +20,7 @@
  *
  * \brief dial() & retrydial() - Trivial application to dial a channel and send an URL on answer
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_dictate.c

@@ -22,6 +22,7 @@
  *
  * \brief Virtual Dictation Machine Application For Asterisk
  *
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_directed_pickup.c

@@ -20,6 +20,7 @@
  *
  * \brief Directed Call Pickup Support
  *
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_directory.c

@@ -20,6 +20,7 @@
  *
  * \brief Provide a directory of extensions
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_disa.c

@@ -3,7 +3,6 @@
  *
  * Copyright (C) 1999 - 2005, Digium, Inc.
  *
- * Jim Dixon <jim@lambdatel.com>
  *
  * Made only slightly more sane by Mark Spencer <markster@digium.com>
  *
@@ -21,7 +20,10 @@
 /*! \file
  *
  * \brief DISA -- Direct Inward System Access Application
+ *
+ * \author Jim Dixon <jim@lambdatel.com>
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_dumpchan.c

@@ -22,6 +22,7 @@
  *
  * \brief Application to dump channel variables
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_echo.c

@@ -20,6 +20,7 @@
  *
  * \brief Echo application -- play back what you hear to evaluate latency
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_enumlookup.c

@@ -20,6 +20,7 @@
  *
  * \brief Enumlookup - lookup entry in ENUM
  *
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_eval.c

@@ -19,6 +19,8 @@
  * \brief Eval application
  *
  * \author Tilghman Lesher <app_eval__v001@the-tilghman.com>
+ *
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_exec.c

@@ -20,6 +20,8 @@
  * \brief Exec application
  *
  * \author Tilghman Lesher <app_exec__v001@the-tilghman.com>
+ *
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_externalivr.c

@@ -23,6 +23,7 @@
  *
  * \brief External IVR application interface
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_festival.c

@@ -20,6 +20,7 @@
  *
  * \brief Connect to festival
  * 
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_flash.c

@@ -20,6 +20,7 @@
  *
  * \brief App to flash a zap trunk
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_forkcdr.c

@@ -19,6 +19,7 @@
  *
  * \brief Fork CDR application
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_getcpeid.c

@@ -18,8 +18,9 @@
 
 /*! \file
  *
- * \brief Execute arbitrary system commands
+ * \brief Get ADSI CPE ID
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_groupcount.c

@@ -20,6 +20,7 @@
  *
  * \brief Group Manipulation Applications
  *
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_hasnewvoicemail.c

@@ -24,6 +24,7 @@
  *
  * \brief HasVoicemail application
  *
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_ices.c

@@ -20,6 +20,7 @@
  *
  * \brief Stream to an icecast server via ICES (see contrib/asterisk-ices.xml)
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_image.c

@@ -20,6 +20,7 @@
  *
  * \brief App to transmit an image
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_intercom.c

@@ -20,6 +20,7 @@
  *
  * \brief Use /dev/dsp as an intercom.
  * 
+ * \ingroup applications
  */
  
 #include <unistd.h>

apps/app_ivrdemo.c

@@ -20,6 +20,7 @@
  *
  * \brief IVR Demo application
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_lookupblacklist.c

@@ -19,6 +19,8 @@
 /*! \file
  *
  * \brief App to lookup the callerid number, and see if it is blacklisted
+ *
+ * \ingroup applications
  * 
  */
 

apps/app_lookupcidname.c

@@ -20,6 +20,7 @@
  *
  * \brief App to set callerid name from database, based on directory number
  * 
+ * \ingroup applications
  */
 
 #include <string.h>

apps/app_macro.c

@@ -20,6 +20,7 @@
  *
  * \brief Dial plan macro Implementation
  * 
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_math.c

@@ -20,6 +20,7 @@
  *
  * \brief A simple math application
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_md5.c

@@ -20,6 +20,7 @@
  * \brief MD5 checksum application
  * 
  * \todo Remove this deprecated application in 1.3dev
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_meetme.c

@@ -20,6 +20,7 @@
  *
  * \brief Meet me conference bridge
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_milliwatt.c

@@ -20,6 +20,7 @@
  *
  * \brief Digital Milliwatt Test
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_mixmonitor.c

@@ -23,6 +23,7 @@
 
 /*! \file
  * \brief MixMonitor() - Record a call and mix the audio during the recording
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_mp3.c

@@ -20,6 +20,7 @@
  *
  * \brief Silly application to play an MP3 file -- uses mpg123
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_nbscat.c

@@ -20,6 +20,7 @@
  *
  * \brief Silly application to play an NBScat file -- uses nbscat8k
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_osplookup.c

@@ -20,6 +20,7 @@
  *
  * \brief Open Settlement Protocol Lookup
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_page.c

@@ -20,6 +20,7 @@
  *
  * \brief page() - Paging application
  *
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_parkandannounce.c

@@ -23,6 +23,7 @@
  *
  * \brief ParkAndAnnounce application for Asterisk
  * 
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_playback.c

@@ -20,6 +20,7 @@
  *
  * \brief Trivial application to playback a sound file
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_privacy.c

@@ -20,6 +20,7 @@
  *
  * \brief Block all calls without Caller*ID, require phone # to be entered
  * 
+ * \ingroup applications
  */
 
 #include <string.h>
@@ -71,8 +72,7 @@ LOCAL_USER_DECL;
 
 
 
-static int
-privacy_exec (struct ast_channel *chan, void *data)
+static int privacy_exec (struct ast_channel *chan, void *data)
 {
 	int res=0;
 	int retries;

apps/app_queue.c

@@ -19,8 +19,10 @@
 /*! \file
  *
  * \brief True call queues with optional send URL on answer
- * 
  *
+ * \arg Config in \ref Config_qu queues.conf
+ * 
+ * \par Development notes
  * \note 2004-11-25: Persistent Dynamic Members added by:
  *             NetNation Communications (www.netnation.com)
  *             Kevin Lindsay <kevinl@netnation.com>
@@ -49,6 +51,7 @@
  * Fixed to work with CVS as of 2004-02-25 and released as 1.07a
  * by Matthew Enger <m.enger@xi.com.au>
  *
+ * \ingroup applications
  */
 
 #include <stdlib.h>
@@ -192,15 +195,15 @@ static char *app_upqm_descrip =
 "same way, except it unpauses instead of pausing the given interface.\n"
 "Example: UnpauseQueueMember(|SIP/3000)\n";
 
-/* Persistent Members astdb family */
+/*! \brief Persistent Members astdb family */
 static const char *pm_family = "/Queue/PersistentMembers";
 /* The maximum lengh of each persistent member queue database entry */
 #define PM_MAX_LEN 2048
 
-/* queues.conf [general] option */
+/*! \brief queues.conf [general] option */
 static int queue_persistent_members = 0;
 
-/* queues.conf per-queue weight option */
+/*! \brief queues.conf per-queue weight option */
 static int use_weight = 0;
 
 enum queue_result {
@@ -226,7 +229,7 @@ const struct {
 	{ QUEUE_FULL, "FULL" },
 };
 
-/* We define a custom "local user" structure because we
+/*! \brief We define a custom "local user" structure because we
    use it not only for keeping track of what is in use but
    also for keeping track of who we're dialing. */
 
@@ -244,34 +247,34 @@ struct localuser {
 LOCAL_USER_DECL;
 
 struct queue_ent {
-	struct ast_call_queue *parent;	/* What queue is our parent */
-	char moh[80];			/* Name of musiconhold to be used */
-	char announce[80];		/* Announcement to play for member when call is answered */
-	char context[AST_MAX_CONTEXT];	/* Context when user exits queue */
-	char digits[AST_MAX_EXTENSION];	/* Digits entered while in queue */
-	int pos;			/* Where we are in the queue */
-	int prio;			/* Our priority */
-	int last_pos_said;              /* Last position we told the user */
-	time_t last_periodic_announce_time;	/* The last time we played a periodic anouncement */
-	time_t last_pos;                /* Last time we told the user their position */
-	int opos;			/* Where we started in the queue */
-	int handled;			/* Whether our call was handled */
-	time_t start;			/* When we started holding */
-	time_t expire;			/* When this entry should expire (time out of queue) */
-	struct ast_channel *chan;	/* Our channel */
-	struct queue_ent *next;		/* The next queue entry */
+	struct ast_call_queue *parent;	/*!< What queue is our parent */
+	char moh[80];			/*!< Name of musiconhold to be used */
+	char announce[80];		/*!< Announcement to play for member when call is answered */
+	char context[AST_MAX_CONTEXT];	/*!< Context when user exits queue */
+	char digits[AST_MAX_EXTENSION];	/*!< Digits entered while in queue */
+	int pos;			/*!< Where we are in the queue */
+	int prio;			/*!< Our priority */
+	int last_pos_said;              /*!< Last position we told the user */
+	time_t last_periodic_announce_time;	/*!< The last time we played a periodic anouncement */
+	time_t last_pos;                /*!< Last time we told the user their position */
+	int opos;			/*!< Where we started in the queue */
+	int handled;			/*!< Whether our call was handled */
+	time_t start;			/*!< When we started holding */
+	time_t expire;			/*!< When this entry should expire (time out of queue) */
+	struct ast_channel *chan;	/*!< Our channel */
+	struct queue_ent *next;		/*!< The next queue entry */
 };
 
 struct member {
-	char interface[80];		/* Technology/Location */
-	int penalty;			/* Are we a last resort? */
-	int calls;			/* Number of calls serviced by this member */
-	int dynamic;			/* Are we dynamically added? */
-	int status;			/* Status of queue member */
-	int paused;			/* Are we paused (not accepting calls)? */
-	time_t lastcall;		/* When last successful call was hungup */
-	int dead;			/* Used to detect members deleted in realtime */
-	struct member *next;		/* Next member */
+	char interface[80];		/*!< Technology/Location */
+	int penalty;			/*!< Are we a last resort? */
+	int calls;			/*!< Number of calls serviced by this member */
+	int dynamic;			/*!< Are we dynamically added? */
+	int status;			/*!< Status of queue member */
+	int paused;			/*!< Are we paused (not accepting calls)? */
+	time_t lastcall;		/*!< When last successful call was hungup */
+	int dead;			/*!< Used to detect members deleted in realtime */
+	struct member *next;		/*!< Next member */
 };
 
 /* values used in multi-bit flags in ast_call_queue */
@@ -282,10 +285,10 @@ struct member {
 
 struct ast_call_queue {
 	ast_mutex_t lock;	
-	char name[80];			/* Name */
-	char moh[80];			/* Music On Hold class to be used */
-	char announce[80];		/* Announcement to play when call is answered */
-	char context[AST_MAX_CONTEXT];	/* Exit context */
+	char name[80];			/*!< Name */
+	char moh[80];			/*!< Music On Hold class to be used */
+	char announce[80];		/*!< Announcement to play when call is answered */
+	char context[AST_MAX_CONTEXT];	/*!< Exit context */
 		unsigned int monjoin:1;
 		unsigned int dead:1;
 		unsigned int joinempty:2;
@@ -298,41 +301,41 @@ struct ast_call_queue {
 		unsigned int strategy:3;
 		unsigned int maskmemberstatus:1;
 		unsigned int realtime:1;
-	int announcefrequency;          /* How often to announce their position */
-	int periodicannouncefrequency;	/* How often to play periodic announcement */
-	int roundingseconds;            /* How many seconds do we round to? */
-	int holdtime;                   /* Current avg holdtime, based on recursive boxcar filter */
-	int callscompleted;             /* Number of queue calls completed */
-	int callsabandoned;             /* Number of queue calls abandoned */
-	int servicelevel;               /* seconds setting for servicelevel*/
-	int callscompletedinsl;         /* Number of calls answered with servicelevel*/
-	char monfmt[8];                 /* Format to use when recording calls */
-	char sound_next[80];            /* Sound file: "Your call is now first in line" (def. queue-youarenext) */
-	char sound_thereare[80];        /* Sound file: "There are currently" (def. queue-thereare) */
-	char sound_calls[80];           /* Sound file: "calls waiting to speak to a representative." (def. queue-callswaiting)*/
-	char sound_holdtime[80];        /* Sound file: "The current estimated total holdtime is" (def. queue-holdtime) */
-	char sound_minutes[80];         /* Sound file: "minutes." (def. queue-minutes) */
-	char sound_lessthan[80];        /* Sound file: "less-than" (def. queue-lessthan) */
-	char sound_seconds[80];         /* Sound file: "seconds." (def. queue-seconds) */
-	char sound_thanks[80];          /* Sound file: "Thank you for your patience." (def. queue-thankyou) */
-	char sound_reporthold[80];	/* Sound file: "Hold time" (def. queue-reporthold) */
-	char sound_periodicannounce[80];/* Sound file: Custom announce, no default */
+	int announcefrequency;          /*!< How often to announce their position */
+	int periodicannouncefrequency;	/*!< How often to play periodic announcement */
+	int roundingseconds;            /*!< How many seconds do we round to? */
+	int holdtime;                   /*!< Current avg holdtime, based on recursive boxcar filter */
+	int callscompleted;             /*!< Number of queue calls completed */
+	int callsabandoned;             /*!< Number of queue calls abandoned */
+	int servicelevel;               /*!< seconds setting for servicelevel*/
+	int callscompletedinsl;         /*!< Number of calls answered with servicelevel*/
+	char monfmt[8];                 /*!< Format to use when recording calls */
+	char sound_next[80];            /*!< Sound file: "Your call is now first in line" (def. queue-youarenext) */
+	char sound_thereare[80];        /*!< Sound file: "There are currently" (def. queue-thereare) */
+	char sound_calls[80];           /*!< Sound file: "calls waiting to speak to a representative." (def. queue-callswaiting)*/
+	char sound_holdtime[80];        /*!< Sound file: "The current estimated total holdtime is" (def. queue-holdtime) */
+	char sound_minutes[80];         /*!< Sound file: "minutes." (def. queue-minutes) */
+	char sound_lessthan[80];        /*!< Sound file: "less-than" (def. queue-lessthan) */
+	char sound_seconds[80];         /*!< Sound file: "seconds." (def. queue-seconds) */
+	char sound_thanks[80];          /*!< Sound file: "Thank you for your patience." (def. queue-thankyou) */
+	char sound_reporthold[80];	/*!< Sound file: "Hold time" (def. queue-reporthold) */
+	char sound_periodicannounce[80];/*!< Sound file: Custom announce, no default */
 
-	int count;			/* How many entries */
-	int maxlen;			/* Max number of entries */
-	int wrapuptime;			/* Wrapup Time */
+	int count;			/*!< How many entries */
+	int maxlen;			/*!< Max number of entries */
+	int wrapuptime;			/*!< Wrapup Time */
 
-	int retry;			/* Retry calling everyone after this amount of time */
-	int timeout;			/* How long to wait for an answer */
-	int weight;                     /* Respective weight */
+	int retry;			/*!< Retry calling everyone after this amount of time */
+	int timeout;			/*!< How long to wait for an answer */
+	int weight;                     /*!< Respective weight */
 	
 	/* Queue strategy things */
-	int rrpos;			/* Round Robin - position */
-	int memberdelay;		/* Seconds to delay connecting member to caller */
+	int rrpos;			/*!< Round Robin - position */
+	int memberdelay;		/*!< Seconds to delay connecting member to caller */
 
-	struct member *members;		/* Head of the list of members */
-	struct queue_ent *head;		/* Head of the list of callers */
-	struct ast_call_queue *next;	/* Next call queue */
+	struct member *members;		/*!< Head of the list of members */
+	struct queue_ent *head;		/*!< Head of the list of callers */
+	struct ast_call_queue *next;	/*!< Next call queue */
 };
 
 static struct ast_call_queue *queues = NULL;
@@ -370,7 +373,7 @@ static int strat2int(const char *strategy)
 	return -1;
 }
 
-/* Insert the 'new' entry after the 'prev' entry of queue 'q' */
+/*! \brief Insert the 'new' entry after the 'prev' entry of queue 'q' */
 static inline void insert_entry(struct ast_call_queue *q, struct queue_ent *prev, struct queue_ent *new, int *pos)
 {
 	struct queue_ent *cur;
@@ -565,7 +568,8 @@ static void clear_queue(struct ast_call_queue *q)
 	q->wrapuptime = 0;
 }
 
-/* Configure a queue parameter.
+/*! \brief Configure a queue parameter.
+\par
    For error reporting, line number is passed for .conf static configuration.
    For Realtime queues, linenum is -1.
    The failunknown flag is set for config files (and static realtime) to show
@@ -727,8 +731,9 @@ static void rt_handle_member_record(struct ast_call_queue *q, char *interface, c
 }
 
 
-/* Reload a single queue via realtime. Return the queue, or NULL if it doesn't exist.
-   Should be called with the global qlock locked.
+/*!\brief Reload a single queue via realtime.
+   \return Return the queue, or NULL if it doesn't exist.
+   \note Should be called with the global qlock locked.
    When found, the queue is returned with q->lock locked. */
 static struct ast_call_queue *reload_queue_rt(const char *queuename, struct ast_variable *queue_vars, struct ast_config *member_config)
 {
@@ -769,7 +774,7 @@ static struct ast_call_queue *reload_queue_rt(const char *queuename, struct ast_
 	if (!queue_vars) {
 		/* Delete queue from in-core list if it has been deleted in realtime. */
 		if (q) {
-			/* Hmm, can't seem to distinguish a DB failure from a not
+			/*! \note Hmm, can't seem to distinguish a DB failure from a not
 			   found condition... So we might delete an in-core queue
 			   in case of DB failure. */
 			ast_log(LOG_DEBUG, "Queue %s not found in realtime.\n", queuename);
@@ -865,7 +870,7 @@ static int join_queue(char *queuename, struct queue_ent *qe, enum queue_result *
 	int inserted = 0;
 	enum queue_member_status stat;
 
-	/* Load from realtime before taking the global qlock, to avoid blocking all
+	/*! \note Load from realtime before taking the global qlock, to avoid blocking all
 	   queue operations while waiting for the DB.
 
 	   This will be two separate database transactions, so we might
@@ -3314,7 +3319,9 @@ static char *complete_queue(char *line, char *word, int pos, int state)
 	return q ? strdup(q->name) : NULL;
 }
 
-/* JDG: callback to display queues status in manager */
+/*!\brief callback to display queues status in manager 
+   \addtogroup Group_AMI 
+ */
 static int manager_queues_show( struct mansession *s, struct message *m )
 {
 	char *a[] = { "show", "queues" };

apps/app_random.c

@@ -20,6 +20,7 @@
  * \brief Random application
  *
  * \author Tilghman Lesher <asterisk__app_random__200508@the-tilghman.com>
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_read.c

@@ -20,6 +20,7 @@
  *
  * \brief Trivial application to read a variable
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_readfile.c

@@ -20,6 +20,7 @@
  *
  * \brief ReadFile application -- Reads in a File for you.
  *
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_realtime.c

@@ -21,6 +21,7 @@
  *
  * \brief RealTime App
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_record.c

@@ -20,6 +20,7 @@
  *
  * \brief Trivial application to record a sound file
  *
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_sayunixtime.c

@@ -19,6 +19,7 @@
  *
  * \brief SayUnixTime application
  * 
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_senddtmf.c

@@ -20,6 +20,7 @@
  *
  * \brief App to send DTMF digits
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_sendtext.c

@@ -20,6 +20,9 @@
  *
  * \brief App to transmit a text message
  * 
+ * Requires support of sending text messages from channel driver
+ *
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_setcallerid.c

@@ -20,6 +20,7 @@
  *
  * \brief App to set callerid
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_setcdruserfield.c

@@ -20,6 +20,7 @@
  *
  * \brief Applictions connected with CDR engine
  * 
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_setcidname.c

@@ -20,6 +20,7 @@
  *
  * \brief App to set callerid
  *
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_setcidnum.c

@@ -21,6 +21,7 @@
  *
  * \brief App to set callerid number
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_setrdnis.c

@@ -21,6 +21,7 @@
  *
  * \brief App to set rdnis
  *
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_settransfercapability.c

@@ -20,6 +20,7 @@
  *
  * \brief App to set the ISDN Transfer Capability
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_skel.c

@@ -20,6 +20,8 @@
  *
  * \brief Skeleton application
  * 
+ * This is a skeleton for development of an Asterisk application */
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_sms.c

@@ -17,6 +17,7 @@
 /*! \file
  *
  * \brief SMS application - ETSI ES 201 912 protocol 1 implimentation
+ * \ingroup applications
  * 
  */
 

apps/app_softhangup.c

@@ -20,6 +20,7 @@
  *
  * \brief SoftHangup application
  * 
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_sql_postgres.c

@@ -20,6 +20,7 @@
  *
  * \brief Connect to PostgreSQL
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_striplsd.c

@@ -20,6 +20,7 @@
  *
  * \brief striplsd: Strip trailing digits app
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_substring.c

@@ -20,6 +20,7 @@
  *
  * \brief substr
  *
+ * \ingroup applications
  * \todo Deprecate this application in 1.3dev
  */
 

apps/app_system.c

@@ -20,6 +20,7 @@
  *
  * \brief Execute arbitrary system commands
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_talkdetect.c

@@ -20,6 +20,7 @@
  *
  * \brief Playback a file with audio detect
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_test.c

@@ -21,6 +21,7 @@
  *
  * \brief Applications to test connection and produce report in text file
  * 
+ * \ingroup applications
  */
 
 #include <sys/types.h>

apps/app_transfer.c

@@ -20,6 +20,9 @@
  *
  * \brief Transfer a caller
  * 
+ * Requires transfer support from channel driver
+ *
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_txtcidname.c

@@ -20,6 +20,7 @@
  *
  * \brief Caller*id name lookup - Look up the caller's name via DNS
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_url.c

@@ -19,6 +19,7 @@
 /*! \file
  * \brief App to transmit a URL
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_userevent.c

@@ -18,6 +18,7 @@
  *
  * \brief UserEvent application -- send manager event
  * 
+ * \ingroup applications
  */
 
 

apps/app_verbose.c

@@ -19,6 +19,7 @@
  *
  * \brief Verbose logging application
  *
+ * \ingroup applications
  */
 
 #include <stdio.h>

apps/app_voicemail.c

@@ -29,6 +29,9 @@
  *
  * \brief Comedian Mail - Voicemail System
  * 
+ * \par See also
+ * \arg \ref Config_vm
+ * \ingroup applications
  */
 
 #include <stdlib.h>
@@ -130,59 +133,62 @@ AST_APP_OPTIONS(vm_app_options, {
 
 static int load_config(void);
 
-/* Syntaxes supported, not really language codes.
-	en - English
-	de - German
-	es - Spanish
-	fr - French
-	it = Italian
-	nl - Dutch
-	pt - Portuguese
-	gr - Greek
-	no - Norwegian
-	se - Swedish
+/*! \page vmlang Voicemail Language Syntaxes Supported
+
+	\par Syntaxes supported, not really language codes.
+	\arg \b en - English
+	\arg \b de - German
+	\arg \b es - Spanish
+	\arg \b fr - French
+	\arg \b it = Italian
+	\arg \b nl - Dutch
+	\arg \b pt - Portuguese
+	\arg \b gr - Greek
+	\arg \b no - Norwegian
+	\arg \b se - Swedish
 
 German requires the following additional soundfile:
-1F	einE (feminine)
+\arg \b 1F	einE (feminine)
 
 Spanish requires the following additional soundfile:
-1M      un (masculine)
+\arg \b 1M      un (masculine)
 
 Dutch, Portuguese & Spanish require the following additional soundfiles:
-vm-INBOXs	singular of 'new'
-vm-Olds		singular of 'old/heard/read'
+\arg \b vm-INBOXs	singular of 'new'
+\arg \b vm-Olds		singular of 'old/heard/read'
 
 NB these are plural:
-vm-INBOX	nieuwe (nl)
-vm-Old		oude (nl)
+\arg \b vm-INBOX	nieuwe (nl)
+\arg \b vm-Old		oude (nl)
 
 Swedish uses:
-vm-nytt		singular of 'new'
-vm-nya		plural of 'new'
-vm-gammalt	singular of 'old'
-vm-gamla	plural of 'old'
-digits/ett	'one', not always same as 'digits/1'
+\arg \b vm-nytt		singular of 'new'
+\arg \b vm-nya		plural of 'new'
+\arg \b vm-gammalt	singular of 'old'
+\arg \b vm-gamla	plural of 'old'
+\arg \b digits/ett	'one', not always same as 'digits/1'
 
 Norwegian uses:
-vm-ny		singular of 'new'
-vm-nye		plural of 'new'
-vm-gammel	singular of 'old'
-vm-gamle	plural of 'old'
+\arg \b vm-ny		singular of 'new'
+\arg \b vm-nye		plural of 'new'
+\arg \b vm-gammel	singular of 'old'
+\arg \b vm-gamle	plural of 'old'
 
 Dutch also uses:
-nl-om		'at'?
+\arg \b nl-om		'at'?
 
 Spanish also uses:
-vm-youhaveno
+\arg \b vm-youhaveno
 
 Italian requires the following additional soundfile:
 
 For vm_intro_it:
-vm-nuovo	new
-vm-nuovi	new plural
-vm-vecchio	old
-vm-vecchi	old plural
-Don't use vm-INBOX or vm-Old, because they are the name of the INBOX and Old folders,
+\arg \b vm-nuovo	new
+\arg \b vm-nuovi	new plural
+\arg \b vm-vecchio	old
+\arg \b vm-vecchi	old plural
+
+\note Don't use vm-INBOX or vm-Old, because they are the name of the INBOX and Old folders,
 spelled among others when you have to change folder. For the above reasons, vm-INBOX
 and vm-Old are spelled plural, to make them sound more as folder name than an adjective.
 
@@ -196,25 +202,25 @@ struct baseio {
 	unsigned char iobuf[BASEMAXINLINE];
 };
 
-/* Structure for linked list of users */
+/*! Structure for linked list of users */
 struct ast_vm_user {
-	char context[AST_MAX_CONTEXT];	/* Voicemail context */
-	char mailbox[AST_MAX_EXTENSION];/* Mailbox id, unique within vm context */
-	char password[80];		/* Secret pin code, numbers only */
-	char fullname[80];		/* Full name, for directory app */
-	char email[80];			/* E-mail address */
-	char pager[80];			/* E-mail address to pager (no attachment) */
-	char serveremail[80];		/* From: Mail address */
-	char mailcmd[160];		/* Configurable mail command */
-	char language[MAX_LANGUAGE];    /* Config: Language setting */
-	char zonetag[80];		/* Time zone */
+	char context[AST_MAX_CONTEXT];	/*!< Voicemail context */
+	char mailbox[AST_MAX_EXTENSION];/*!< Mailbox id, unique within vm context */
+	char password[80];		/*!< Secret pin code, numbers only */
+	char fullname[80];		/*!< Full name, for directory app */
+	char email[80];			/*!< E-mail address */
+	char pager[80];			/*!< E-mail address to pager (no attachment) */
+	char serveremail[80];		/*!< From: Mail address */
+	char mailcmd[160];		/*!< Configurable mail command */
+	char language[MAX_LANGUAGE];    /*!< Config: Language setting */
+	char zonetag[80];		/*!< Time zone */
 	char callback[80];
 	char dialout[80];
-	char uniqueid[20];		/* Unique integer identifier */
+	char uniqueid[20];		/*!< Unique integer identifier */
 	char exit[80];
-	unsigned int flags;		/* VM_ flags */	
+	unsigned int flags;		/*!< VM_ flags */	
 	int saydurationm;
-	int maxmsg;			/* Maximum number of msgs per folder for this mailbox */
+	int maxmsg;			/*!< Maximum number of msgs per folder for this mailbox */
 	struct ast_vm_user *next;
 };
 

apps/app_waitforring.c

@@ -20,6 +20,7 @@
  *
  * \brief Wait for Ring Application
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_waitforsilence.c

@@ -22,10 +22,11 @@
 /*! \file
  *
  * \brief Wait for Silence
- *   - Waits for up to 'x' milliseconds of silence, 'y' times
- *   - WaitForSilence(500,2) will wait for 1/2 second of silence, twice
- *   - WaitForSilence(1000,1) will wait for 1 second of silence, once
+ *   - Waits for up to 'x' milliseconds of silence, 'y' times \n
+ *   - WaitForSilence(500,2) will wait for 1/2 second of silence, twice \n
+ *   - WaitForSilence(1000,1) will wait for 1 second of silence, once \n
  *
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_while.c

@@ -20,6 +20,7 @@
  *
  * \brief While Loop and ExecIf Implementations
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_zapateller.c

@@ -20,6 +20,7 @@
  *
  * \brief Playback the special information tone to get rid of telemarketers
  * 
+ * \ingroup applications
  */
  
 #include <string.h>

apps/app_zapbarge.c

@@ -23,6 +23,7 @@
  *
  * \brief Zap Barge support
  * 
+ * \ingroup applications
  */
 
 #include <stdlib.h>

apps/app_zapras.c

@@ -20,6 +20,7 @@
  *
  * \brief Execute an ISDN RAS
  * 
+ * \ingroup applications
  */
 
 #include <sys/ioctl.h>

apps/app_zapscan.c

@@ -25,6 +25,7 @@
  *
  * \brief Zap Scanner
  *
+ * \ingroup applications
  */
 
 #include <stdlib.h>

cdr/cdr_csv.c

@@ -23,6 +23,7 @@
  * \brief Comma Separated Value CDR records.
  * 
  * \arg See also \ref AstCDR
+ * \ingroup cdr_drivers
  */
 
 #include <sys/types.h>

cdr/cdr_custom.c

@@ -25,6 +25,7 @@
  * \arg See also \ref AstCDR
  *
  * Logs in LOG_DIR/cdr_custom
+ * \ingroup cdr_drivers
  */
 
 #include <sys/types.h>

cdr/cdr_manager.c

@@ -22,6 +22,7 @@
  * \arg \ref AstCDR
  * \arg \ref AstAMI
  * \arg \ref Config_ami
+ * \ingroup cdr_drivers
  */
 
 #include <sys/types.h>

cdr/cdr_odbc.c

@@ -25,6 +25,7 @@
  * See also:
  * \arg http://www.unixodbc.org
  * \arg \ref Config_cdr
+ * \ingroup cdr_drivers
  */
 
 #include <sys/types.h>

cdr/cdr_pgsql.c

@@ -29,6 +29,7 @@
  * See also
  * \arg \ref Config_cdr
  * \arg http://www.postgresql.org/
+ * \ingroup cdr_drivers
  */
 
 #include <sys/types.h>

cdr/cdr_sqlite.c

@@ -28,6 +28,7 @@
  * \arg http://www.sqlite.org/
  * 
  * Creates the database and table on-the-fly
+ * \ingroup cdr_drivers
  */
 
 #include <sys/types.h>

cdr/cdr_tds.c

@@ -21,6 +21,7 @@
  * See also
  * \arg \ref Config_cdr
  * \arg http://www.freetds.org/
+ * \ingroup cdr_drivers
  */
 
 /*! \verbatim

channels/chan_agent.c

@@ -18,10 +18,14 @@
 
 
 /*! \file
- * \brief Implementation of Agents
+ * \brief Implementation of Agents (proxy channel)
  *
  * This file is the implementation of Agents modules.
- * It is a dynamic module that is loaded by Asterisk. At load time, load_module is run.
+ * It is a dynamic module that is loaded by Asterisk. 
+ * \par See also
+ * \arg \ref Config_agent
+ *
+ * \ingroup channel_drivers
  */
 
 #include <stdio.h>

channels/chan_alsa.c

@@ -18,6 +18,11 @@
 
 /*! \file 
  * \brief ALSA sound card channel driver 
+ *
+ * \par See also
+ * \arg Config_alsa
+ *
+ * \ingroup channel_drivers
  */
 
 

channels/chan_features.c

@@ -22,6 +22,7 @@
  * 
  * \note *** Experimental code ****
  * 
+ * \ingroup channel_drivers
  */
 
 #include <stdio.h>

channels/chan_h323.c

@@ -25,6 +25,10 @@
  *
  * \brief This file is part of the chan_h323 driver for Asterisk
  *
+ * \par See also
+ * \arg Config_h323
+ *
+ * \ingroup channel_drivers
  */
 
 #include <sys/socket.h>

channels/chan_iax2.c

@@ -20,6 +20,10 @@
  *
  * \brief Implementation of Inter-Asterisk eXchange Version 2
  *
+ * \par See also
+ * \arg \ref Config_iax
+ *
+ * \ingroup channel_drivers
  */
 
 #include "asterisk.h"
@@ -7694,6 +7698,9 @@ static char *pdescrip =
 "the calling entity is in fact an IAXy) with the given template or\n"
 "default if one is not specified.  Returns -1 on error or 0 on success.\n";
 
+/*! iax2provision
+\ingroup applications
+*/
 static int iax2_prov_app(struct ast_channel *chan, void *data)
 {
 	int res;

channels/chan_local.c

@@ -20,6 +20,7 @@
  *
  * \brief Local Proxy Channel
  * 
+ * \ingroup channel_drivers
  */
 
 #include <stdio.h>

channels/chan_mgcp.c

@@ -20,6 +20,10 @@
  *
  * \brief Implementation of Media Gateway Control Protocol
  * 
+ * \par See also
+ * \arg \ref Config_mgcp
+ *
+ * \ingroup channel_drivers
  */
 
 /* FO: Changes

channels/chan_misdn.c

@@ -1,14 +1,29 @@
 /*
- * Chan_Misdn -- Channel Driver for Asterisk
- *
- * Interface to Asterisk
- *
+ * Asterisk -- An open source telephony toolkit.
+ * 
  * Copyright (C) 2004, Christian Richter
  *
  * Christian Richter <crich@beronet.com>
  *
+ * 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
+ * channels for your use.
+ *
  * This program is free software, distributed under the terms of
- * the GNU General Public License
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ *
+ */
+
+/*!
+ * \file
+ *
+ * \brief the chan_misdn channel driver for Asterisk
+ * \author Christian Richter <crich@beronet.com>
+ *
+ * \ingroup channel_drivers
  */
 
 #include <stdio.h>
@@ -56,23 +71,23 @@ ast_mutex_t release_lock_mutex;
 /* BEGIN: chan_misdn.h */
 
 enum misdn_chan_state {
-	MISDN_NOTHING, /* at beginning */
-	MISDN_WAITING4DIGS, /*  when waiting for infos */
-	MISDN_EXTCANTMATCH, /*  when asterisk couldnt match our ext */
-	MISDN_DIALING, /*  when pbx_start */
-	MISDN_PROGRESS, /*  we got a progress */
-	MISDN_CALLING, /*  when misdn_call is called */
-	MISDN_CALLING_ACKNOWLEDGE, /*  when we get SETUP_ACK */
-	MISDN_ALERTING, /*  when Alerting */
-	MISDN_BUSY, /*  when BUSY */
-	MISDN_CONNECTED, /*  when connected */
-	MISDN_BRIDGED, /*  when bridged */
-	MISDN_CLEANING, /* when hangup from * but we were connected before */
-	MISDN_HUNGUP_FROM_MISDN, /* when DISCONNECT/RELEASE/REL_COMP  cam from misdn */
-	MISDN_HUNGUP_FROM_AST, /* when DISCONNECT/RELEASE/REL_COMP came out of */
+	MISDN_NOTHING,		/*!< at beginning */
+	MISDN_WAITING4DIGS, /*!<  when waiting for infos */
+	MISDN_EXTCANTMATCH, /*!<  when asterisk couldnt match our ext */
+	MISDN_DIALING, /*!<  when pbx_start */
+	MISDN_PROGRESS, /*!<  we got a progress */
+	MISDN_CALLING, /*!<  when misdn_call is called */
+	MISDN_CALLING_ACKNOWLEDGE, /*!<  when we get SETUP_ACK */
+	MISDN_ALERTING, /*!<  when Alerting */
+	MISDN_BUSY, /*!<  when BUSY */
+	MISDN_CONNECTED, /*!<  when connected */
+	MISDN_BRIDGED, /*!<  when bridged */
+	MISDN_CLEANING, /*!< when hangup from * but we were connected before */
+	MISDN_HUNGUP_FROM_MISDN, /*!< when DISCONNECT/RELEASE/REL_COMP  cam from misdn */
+	MISDN_HUNGUP_FROM_AST, /*!< when DISCONNECT/RELEASE/REL_COMP came out of */
 	/* misdn_hangup */
-	MISDN_HOLDED, /* if this chan is holded */
-	MISDN_HOLD_DISCONNECT /* if this chan is holded */
+	MISDN_HOLDED, /*!< if this chan is holded */
+	MISDN_HOLD_DISCONNECT /*!< if this chan is holded */
   
 };