Documentation updates

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

5 files changed, 92 insertions, 35 deletions

diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index 6521e9762..ff0901fb2 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -143,6 +143,8 @@ enum ast_bridge_result {
 
 typedef unsigned long long ast_group_t;
 
+/*! \todo Add an explanation of an Asterisk generator 
+*/
 struct ast_generator {
 	void *(*alloc)(struct ast_channel *chan, void *params);
 	void (*release)(struct ast_channel *chan, void *data);
@@ -274,8 +276,8 @@ struct ast_channel_tech {
 	int (* func_channel_write)(struct ast_channel *chan, char *function, char *data, const char *value);
 };
 
-struct ast_channel_spy_list;
-struct ast_channel_whisper_buffer;
+struct ast_channel_spy_list;	/*!< \todo Add explanation here */
+struct ast_channel_whisper_buffer;	/*!< \todo Add explanation here */
 
 #define	DEBUGCHAN_FLAG  0x80000000
 #define	FRAMECOUNT_INC(x)	( ((x) & DEBUGCHAN_FLAG) | ((x++) & ~DEBUGCHAN_FLAG) )
@@ -492,6 +494,7 @@ enum {
 	AST_FEATURE_PARKCALL =     (1 << 5),
 };
 
+/*! \brief bridge configuration */
 struct ast_bridge_config {
 	struct ast_flags features_caller;
 	struct ast_flags features_callee;
@@ -750,7 +753,7 @@ int ast_call(struct ast_channel *chan, char *addr, int timeout);
 int ast_indicate(struct ast_channel *chan, int condition);
 
 /*! \brief Indicates condition of channel, with payload
- * \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
+ * \note Indicate a condition such as AST_CONTROL_HOLD with payload being music on hold class
  * \param chan channel to change the indication
  * \param condition which condition to indicate on the channel
  * \param data pointer to payload data
@@ -817,14 +820,12 @@ int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
 
 /*! \brief Reads a frame
  * \param chan channel to read a frame from
-	Read a frame.  
-	\return Returns a frame, or NULL on error.  If it returns NULL, you
-		best just stop reading frames and assume the channel has been
-		disconnected. */
+ * \return Returns a frame, or NULL on error.  If it returns NULL, you
+	best just stop reading frames and assume the channel has been
+	disconnected. */
 struct ast_frame *ast_read(struct ast_channel *chan);
 
 /*! \brief Reads a frame, returning AST_FRAME_NULL frame if audio. 
- * Read a frame. 
  	\param chan channel to read a frame from
 	\return  Returns a frame, or NULL on error.  If it returns NULL, you
 		best just stop reading frames and assume the channel has been
@@ -892,7 +893,20 @@ int ast_recvchar(struct ast_channel *chan, int timeout);
  */
 int ast_senddigit(struct ast_channel *chan, char digit);
 
+/*! \brief Send a DTMF digit to a channel
+ * Send a DTMF digit to a channel.
+ * \param chan channel to act upon
+ * \param digit the DTMF digit to send, encoded in ASCII
+ * \return Returns 0 on success, -1 on failure
+ */
 int ast_senddigit_begin(struct ast_channel *chan, char digit);
+/*! \brief Send a DTMF digit to a channel
+
+ * Send a DTMF digit to a channel.
+ * \param chan channel to act upon
+ * \param digit the DTMF digit to send, encoded in ASCII
+ * \return Returns 0 on success, -1 on failure
+ */
 int ast_senddigit_end(struct ast_channel *chan, char digit);
 
 /*! \brief Receives a text string from a channel
@@ -1350,7 +1364,7 @@ struct ast_variable *ast_channeltype_list(void);
   audio samples, and then to mix in audio from the whisper buffer if it
   is available.
 
-  Note: This function performs no locking; you must hold the channel's lock before
+  \note Note: This function performs no locking; you must hold the channel's lock before
   calling this function.
  */
 int ast_channel_whisper_start(struct ast_channel *chan);
diff --git a/include/asterisk/devicestate.h b/include/asterisk/devicestate.h
index 97d24c16f..85a1235c9 100644
--- a/include/asterisk/devicestate.h
+++ b/include/asterisk/devicestate.h
@@ -18,6 +18,8 @@
 
 /*! \file
  * \brief Device state management
+ *
+ * \arg See \ref AstExtState
  */
 
 #ifndef _ASTERISK_DEVICESTATE_H
@@ -26,25 +28,18 @@
 #if defined(__cplusplus) || defined(c_plusplus)
 extern "C" {
 #endif
-
-/*! Device is valid but channel didn't know state */
-#define AST_DEVICE_UNKNOWN	0
-/*! Device is not used */
-#define AST_DEVICE_NOT_INUSE	1
-/*! Device is in use */
-#define AST_DEVICE_INUSE	2
-/*! Device is busy */
-#define AST_DEVICE_BUSY		3
-/*! Device is invalid */
-#define AST_DEVICE_INVALID	4
-/*! Device is unavailable */
-#define AST_DEVICE_UNAVAILABLE	5
-/*! Device is ringing */
-#define AST_DEVICE_RINGING	6
-/*! Device is ringing *and* in use */
-#define AST_DEVICE_RINGINUSE	7
-/*! Device is on hold */
-#define AST_DEVICE_ONHOLD	8
+/*! @name DeviceStates */
+/*! \@{ */
+#define AST_DEVICE_UNKNOWN	0 /*!< Device is valid but channel didn't know state */
+#define AST_DEVICE_NOT_INUSE	1 /*!< Device is not used */
+#define AST_DEVICE_INUSE	2 /*!< Device is in use */
+#define AST_DEVICE_BUSY		3 /*!< Device is busy */
+#define AST_DEVICE_INVALID	4 /*!< Device is invalid */
+#define AST_DEVICE_UNAVAILABLE	5 /*!< Device is unavailable */
+#define AST_DEVICE_RINGING	6 /*!< Device is ringing */
+#define AST_DEVICE_RINGINUSE	7 /*!< Device is ringing *and* in use */
+#define AST_DEVICE_ONHOLD	8 /*!< Device is on hold */
+/*! \@} */
 
 /*! \brief Devicestate watcher call back */
 typedef int (*ast_devstate_cb_type)(const char *dev, int state, void *data);
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index fbaef5477..17e7b1416 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -43,7 +43,10 @@ extern "C" {
 
 #define PRIORITY_HINT	-1	/*!< Special Priority for a hint */
 
-/*! \brief Extension states */
+/*! \brief Extension states 
+	\note States can be combined 
+	- \ref AstExtState
+*/
 enum ast_extension_states {
 	AST_EXTENSION_REMOVED = -2,	/*!< Extension removed */
 	AST_EXTENSION_DEACTIVATED = -1,	/*!< Extension hint removed */
@@ -174,6 +177,20 @@ int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data);
  * \return NULL on failure, and an ast_context structure on success
  */
 struct ast_context *ast_context_create(struct ast_context **extcontexts, const char *name, const char *registrar);
+
+/*!
+ * \brief Register a new context or find an existing one
+ *
+ * \param extcontexts pointer to the ast_context structure pointer
+ * \param name name of the new context
+ * \param registrar registrar of the context
+ *
+ * This will first search for a context with your name.  If it exists already, it will not
+ * create a new one.  If it does not exist, it will create a new one with the given name
+ * and registrar.
+ *
+ * \return NULL on failure, and an ast_context structure on success
+ */
 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, const char *name, const char *registrar);
 
 /*!
@@ -211,6 +228,11 @@ void ast_context_destroy(struct ast_context *con, const char *registrar);
  */
 struct ast_context *ast_context_find(const char *name);
 
+/*! \brief The result codes when starting the PBX on a channel
+	with \ref ast_pbx_start()
+
+	AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
+ */
 enum ast_pbx_result {
 	AST_PBX_SUCCESS = 0,
 	AST_PBX_FAILED = -1,
@@ -356,7 +378,7 @@ int ast_extension_state_add(const char *context, const char *exten,
 int ast_extension_state_del(int id, ast_state_cb_type callback);
 
 /*! 
- * \brief If an extension exists, return non-zero
+ * \brief If an extension hint exists, return non-zero
  * 
  * \param hint buffer for hint
  * \param maxlen size of hint buffer
@@ -728,7 +750,9 @@ int ast_pbx_outgoing_app(const char *type, int format, void *data, int timeout,
  */
 int pbx_checkcondition(const char *condition);
 
-/* Functions for returning values from structures */
+/*! @name 
+ * Functions for returning values from structures */
+/*! @{ */
 const char *ast_get_context_name(struct ast_context *con);
 const char *ast_get_extension_name(struct ast_exten *exten);
 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
@@ -736,21 +760,26 @@ const char *ast_get_include_name(struct ast_include *include);
 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
 const char *ast_get_switch_name(struct ast_sw *sw);
 const char *ast_get_switch_data(struct ast_sw *sw);
+/*! @} */
 
-/* Other extension stuff */
+/*! @name Other Extension stuff */
+/*! @{ */
 int ast_get_extension_priority(struct ast_exten *exten);
 int ast_get_extension_matchcid(struct ast_exten *e);
 const char *ast_get_extension_cidmatch(struct ast_exten *e);
 const char *ast_get_extension_app(struct ast_exten *e);
 const char *ast_get_extension_label(struct ast_exten *e);
 void *ast_get_extension_app_data(struct ast_exten *e);
+/*! @} */
 
-/* Registrar info functions ... */
+/*! @name Registrar info functions ... */
+/*! @{ */
 const char *ast_get_context_registrar(struct ast_context *c);
 const char *ast_get_extension_registrar(struct ast_exten *e);
 const char *ast_get_include_registrar(struct ast_include *i);
 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
 const char *ast_get_switch_registrar(struct ast_sw *sw);
+/*! @} */
 
 /* Walking functions ... */
 struct ast_context *ast_walk_contexts(struct ast_context *con);
diff --git a/main/devicestate.c b/main/devicestate.c
index 2fd8d82bd..4a881afef 100644
--- a/main/devicestate.c
+++ b/main/devicestate.c
@@ -67,7 +67,7 @@
  *	system. res_jabber.c can subscribe and watch such states
  *	in jabber/xmpp based systems.
  *
- *	\section AstExtStateARch Architecture
+ *	\section AstDevStateArch Architecture for devicestates
  *
  *	When a channel driver or asterisk app changes state for 
  *	a watched object, it alerts the core. The core queues
@@ -84,9 +84,26 @@
  *	- Device states
  *		\arg \ref devicestate.c 
  *		\arg \ref devicestate.h 
+ *
+ *	\section AstExtStateArch Architecture for extension states
+ *	
+ *	Hints are connected to extension. If an extension changes state
+ *	it checks the hint devices. If there is a hint, the callbacks into
+ *	device states are checked. The aggregated state is set for the hint
+ *	and reported back.
+ *
  *	- Extension states
+ *		\arg \ref enum ast_extension_states
  *		\arg \ref pbx.c 
  *		\arg \ref pbx.h 
+ *	- Structures
+ *		- \ref struct ast_state_cb  Callbacks for watchers
+ *		- Callback ast_state_cb_type
+ *		- \ref struct ast_hint
+ * 	- Functions
+ *		- ast_extension_state_add()
+ *		- ast_extension_state_del()
+ *		- ast_get_hint()
  *	
  */
 
diff --git a/main/pbx.c b/main/pbx.c
index 60a89e104..370087412 100644
--- a/main/pbx.c
+++ b/main/pbx.c
@@ -193,7 +193,9 @@ struct ast_state_cb {
 /*! \brief Structure for dial plan hints
 
   \note Hints are pointers from an extension in the dialplan to one or
-  more devices (tech/name) */
+  more devices (tech/name) 
+	- See \ref AstExtState
+*/
 struct ast_hint {
 	struct ast_exten *exten;	/*!< Extension */
 	int laststate; 			/*!< Last known state */