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

1 files changed, 62 insertions, 0 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