Doxygen update

- Document cause codes
- Document a bit more on channel variables - global, predefined and local
- Fix some doxygen in channel.h. Adding one comment for two definitions does not
  work. They won't be copied to each.


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@47986 f38db490-d61c-443f-a65b-d21fe96a405b

4 files changed, 148 insertions, 22 deletions

diff --git a/include/asterisk/causes.h b/include/asterisk/causes.h
index fc27c7970..ad3fa672d 100644
--- a/include/asterisk/causes.h
+++ b/include/asterisk/causes.h
@@ -23,6 +23,68 @@
 #ifndef _ASTERISK_CAUSES_H
 #define _ASTERISK_CAUSES_H
 
+/*! \page AstCauses Hangup Causes for Asterisk
+
+The Asterisk hangup causes are delivered to the dialplan in the
+${HANGUPCAUSE} channel variable after a call (after execution
+of "dial"). 
+
+In SIP, we have a conversion table to convert between SIP
+return codes and Q.931 both ways. This is to improve SIP/ISDN
+compatibility.
+
+These are the current codes, based on the Q.931
+specification:
+
+	- AST_CAUSE_UNALLOCATED				1
+	- AST_CAUSE_NO_ROUTE_TRANSIT_NET			2
+	- AST_CAUSE_NO_ROUTE_DESTINATION			3
+	- AST_CAUSE_CHANNEL_UNACCEPTABLE			6
+	- AST_CAUSE_CALL_AWARDED_DELIVERED		7
+	- AST_CAUSE_NORMAL_CLEARING			16
+	- AST_CAUSE_USER_BUSY				17
+	- AST_CAUSE_NO_USER_RESPONSE			18
+	- AST_CAUSE_NO_ANSWER				19
+	- AST_CAUSE_CALL_REJECTED				21
+	- AST_CAUSE_NUMBER_CHANGED			22
+	- AST_CAUSE_DESTINATION_OUT_OF_ORDER		27
+	- AST_CAUSE_INVALID_NUMBER_FORMAT			28
+	- AST_CAUSE_FACILITY_REJECTED			29
+	- AST_CAUSE_RESPONSE_TO_STATUS_ENQUIRY		30
+	- AST_CAUSE_NORMAL_UNSPECIFIED			31
+	- AST_CAUSE_NORMAL_CIRCUIT_CONGESTION		34
+	- AST_CAUSE_NETWORK_OUT_OF_ORDER			38
+	- AST_CAUSE_NORMAL_TEMPORARY_FAILURE		41
+	- AST_CAUSE_SWITCH_CONGESTION			42
+	- AST_CAUSE_ACCESS_INFO_DISCARDED			43
+	- AST_CAUSE_REQUESTED_CHAN_UNAVAIL		44
+	- AST_CAUSE_PRE_EMPTED				45
+	- AST_CAUSE_FACILITY_NOT_SUBSCRIBED  		50
+	- AST_CAUSE_OUTGOING_CALL_BARRED     		52
+	- AST_CAUSE_INCOMING_CALL_BARRED     		54
+	- AST_CAUSE_BEARERCAPABILITY_NOTAUTH		57
+	- AST_CAUSE_BEARERCAPABILITY_NOTAVAIL     	58
+	- AST_CAUSE_BEARERCAPABILITY_NOTIMPL		65
+	- AST_CAUSE_CHAN_NOT_IMPLEMENTED     		66
+	- AST_CAUSE_FACILITY_NOT_IMPLEMENTED      	69
+	- AST_CAUSE_INVALID_CALL_REFERENCE		81
+	- AST_CAUSE_INCOMPATIBLE_DESTINATION		88
+	- AST_CAUSE_INVALID_MSG_UNSPECIFIED  		95
+	- AST_CAUSE_MANDATORY_IE_MISSING			96
+	- AST_CAUSE_MESSAGE_TYPE_NONEXIST			97
+	- AST_CAUSE_WRONG_MESSAGE				98
+	- AST_CAUSE_IE_NONEXIST				99
+	- AST_CAUSE_INVALID_IE_CONTENTS			100
+	- AST_CAUSE_WRONG_CALL_STATE			101
+	- AST_CAUSE_RECOVERY_ON_TIMER_EXPIRE		102
+	- AST_CAUSE_MANDATORY_IE_LENGTH_ERROR		103
+	- AST_CAUSE_PROTOCOL_ERROR			111
+	- AST_CAUSE_INTERWORKING				127
+
+For more information:
+- \ref app_dial.c
+*/
+
 /* Causes for disconnection (from Q.931) */
 #define AST_CAUSE_UNALLOCATED				1
 #define AST_CAUSE_NO_ROUTE_TRANSIT_NET			2
diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index 94b46a916..6521e9762 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -84,6 +84,11 @@
 
 */
 
+/*! \page AstFileDesc File descriptors 
+	Asterisk File descriptors are connected to each channel (see \ref Def_Channel)
+	in the \ref ast_channel structure.
+*/
+
 #ifndef _ASTERISK_CHANNEL_H
 #define _ASTERISK_CHANNEL_H
 
@@ -336,8 +341,8 @@ struct ast_channel {
 		AST_STRING_FIELD(uniqueid);		/*!< Unique Channel Identifier */
 	);
 	
-	/*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
-	int fds[AST_MAX_FDS];			
+	/*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  See \ref AstFileDesc */
+	int fds[AST_MAX_FDS];	
 
 	void *music_state;				/*!< Music State*/
 	void *generatordata;				/*!< Current generator data if there is any */
@@ -351,12 +356,11 @@ struct ast_channel {
 	struct ast_channel *masqr;			/*!< Who we are masquerading as */
 	int cdrflags;					/*!< Call Detail Record Flags */
 
-	/*! \brief Whether or not we have been hung up...  Do not set this value
-	    directly, use ast_softhangup */
-	int _softhangup;
+	int _softhangup;				/*!< Whether or not we have been hung up...  Do not set this value
+	    							directly, use ast_softhangup() */
 	time_t	whentohangup;				/*!< Non-zero, set to actual time when channel is to be hung up */
 	pthread_t blocker;				/*!< If anyone is blocking, this is them */
-	ast_mutex_t lock;				/*!< Lock, can be used to lock a channel for some operations */
+	ast_mutex_t lock;				/*!< Lock, can be used to lock a channel for some operations - see ast_channel_lock() */
 	const char *blockproc;				/*!< Procedure causing blocking */
 
 	const char *appl;				/*!< Current application */
@@ -373,7 +377,7 @@ struct ast_channel {
 	int (*timingfunc)(void *data);
 	void *timingdata;
 
-	enum ast_channel_state _state;			/*!< State of line -- Don't write directly, use ast_setstate */
+	enum ast_channel_state _state;			/*!< State of line -- Don't write directly, use ast_setstate() */
 	int rings;					/*!< Number of rings so far */
 	struct ast_callerid cid;			/*!< Caller ID, name, presentation etc */
 	char dtmfq[AST_MAX_EXTENSION];			/*!< Any/all queued DTMF characters */
@@ -397,17 +401,16 @@ struct ast_channel {
 
 	struct ast_channel_monitor *monitor;		/*!< Channel monitoring */
 
-	/*! Track the read/written samples for monitor use */
-	unsigned long insmpl;
-	unsigned long outsmpl;
+	unsigned long insmpl;				/*!< Track the read/written samples for monitor use */
+	unsigned long outsmpl;				/*!< Track the read/written samples for monitor use */
 
-	/* Frames in/out counters. The high bit is a debug mask, so
-	 * the counter is only in the remaining bits
-	 */
-	unsigned int fin;
-	unsigned int fout;
+	unsigned int fin;				/*!< Frames in counters. The high bit is a debug mask, so
+	 						 * the counter is only in the remaining bits */
+	unsigned int fout;				/*!< Frames out counters. The high bit is a debug mask, so
+	 						 * the counter is only in the remaining bits */
 	int hangupcause;				/*!< Why is the channel hanged up. See causes.h */
-	struct varshead varshead;			/*!< A linked list for channel variables */
+	struct varshead varshead;			/*!< A linked list for channel variables 
+								(see \ref AstChanVar ) */
 	ast_group_t callgroup;				/*!< Call group for call pickups */
 	ast_group_t pickupgroup;			/*!< Pickup group - which calls groups can be picked up? */
 	unsigned int flags;				/*!< channel flags of AST_FLAG_ type */
diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h
index 49e282816..9211b1233 100644
--- a/include/asterisk/doxyref.h
+++ b/include/asterisk/doxyref.h
@@ -135,9 +135,67 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  *  \verbinclude video.txt
  */
 
-/*! \page AstVar Global channel variables
- * \section globchan Global 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.
+ * Some still exist though and some that does still exist needs to move to
+ * dialplan functions.
+ *
+ * See also
+ * - \ref pbx_retrieve_variable()
+ * - \ref AstChanVar
+ *
  *  \verbinclude channelvariables.txt
+
+ */
+
+/*! \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
+ *	- Channel variables, that exist during a channel
+ *
+ * Global variables are reachable in all channels, all of the time.
+ * Channel variables are only reachable within the channel.
+ *
+ * For more information on the predefined variables, see \ref AstVar
+ * 
+ * Global and Channel variables:
+ * - Names are Case insensitive
+ * - Names that start with a character, but are alphanumeric
+ * - Global variables are defined and reached with the GLOBAL() dialplan function
+ *   and the set application, like
+ *
+ * 	exten => 1234,1,set(GLOBAL(myvariable)=tomteluva)
+ *
+ * 	- \ref func_global.c
+ *
+ * - Channel variables are defined with the set() dialplan application
+ *
+ *	exten => 1234,1,set(xmasattribute=tomtegröt)
+ *
+ * - Some channels also supports setting channel variables with the \b setvar=
+ *   configuraiton option for a device or line.
+ *
+ * \section AstChanVar_globalvars Global Variables
+ * Global variables can also be set in the [globals] section of extensions.conf. The
+ * setting \b clearglobalvars in extensions.conf [general] section affects whether
+ * or not the global variables defined in \b globals are reset at dialplan reload.
+ * 
+ * There are CLI commands to change and read global variables. This can be handy
+ * to reset counters at midnight from an external script.
+ *
+ * \section AstChanVar_devnotes Developer notes
+ * Variable handling is managed within \ref pbx.c
+ * You need to include pbx.h to reach these functions.
+ *	- \ref pbx_builtin_setvar_helper()
+ * 	- \ref pbx_builtin_getvar_helper()
+ *
+ * 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
@@ -209,7 +267,7 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \verbinclude features.conf.sample
  */
 
-/*! \page Config_followme followme.conf 
+/*! \page Config_followme Followme: An application for simple follow-me calls
  * \section followmeconf Followme.conf
  * - See app_followme.c
  * \verbinclude followme.conf.sample
diff --git a/main/pbx.c b/main/pbx.c
index f79461e4c..60a89e104 100644
--- a/main/pbx.c
+++ b/main/pbx.c
@@ -1094,9 +1094,12 @@ static char *substring(const char *value, int offset, int length, char *workspac
 	return ret;
 }
 
-/*! \brief  pbx_retrieve_variable: Support for Asterisk built-in variables and
-      functions in the dialplan
-  ---*/
+/*! \brief  Support for Asterisk built-in variables and functions in the dialplan
+
+\note	See also
+	- \ref AstVar	Channel variables
+	- \ref AstCauses The HANGUPCAUSE variable
+ */
 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp)
 {
 	const char not_found = '\0';