[svn-commits] mmichelson: branch group/CCSS r247969 - /team/group/CCSS/include/asterisk/ccss.h

Fri Feb 19 12:27:03 CST 2010

Author: mmichelson
Date: Fri Feb 19 12:26:59 2010
New Revision: 247969

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=247969
Log:
More doxygen makeovers.


Modified:
    team/group/CCSS/include/asterisk/ccss.h

Modified: team/group/CCSS/include/asterisk/ccss.h
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/include/asterisk/ccss.h?view=diff&rev=247969&r1=247968&r2=247969
==============================================================================

--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Fri Feb 19 12:26:59 2010
@@ -477,29 +477,32 @@
  * placement in the tree, such as who its parent is.
  */
 struct ast_cc_monitor {
-	/* Information regarding the interface.
+	/*!
+	 * Information regarding the interface.
 	 */
 	struct ast_cc_interface *interface;
-	/* Every interface has an id associated with it. Think of
-	 * it like a "primary key"
+	/*!
+	 * Every interface has an id that uniquely identifies it. It is
+	 * formed by incrementing a counter.
 	 */
 	unsigned int id;
-	/* Who is this interface's parent interface? The "root" of
-	 * the tree will have 0 for this. Everyone else will have at
-	 * least 1 as their parent_id.
+	/*!
+	 * The ID of this monitor's parent. If this monitor is at the
+	 * top of the tree, then his parent will be 0.
 	 */
 	unsigned int parent_id;
-	/* The instance of the CC core to which this monitor belongs
+	/*! 
+	 * The instance of the CC core to which this monitor belongs
 	 */
 	int core_id;
-	/* What service was offered by the endpoint. Note that
-	 * this field is completely irrelevant for cc_monitors
-	 * representing dialplan extensions.
+	/*!
+	 * The type of call completion service offered by a device.
 	 */
 	enum ast_cc_service_type service_offered;
 	/*!
-	 * Name that should be used to recall specified interface
-	 *
+	 * \brief Name that should be used to recall specified interface
+	 *
+	 * \details
 	 * When issuing a CC recall, some technologies will require
 	 * that a name other than the device name is dialed. For instance,
 	 * with SIP, a specific URI will be used which chan_sip will be able
@@ -515,6 +518,15 @@
 	 * Monitor callbacks
 	 */
 	const struct ast_cc_monitor_callbacks *callbacks;
+	/*!
+	 * \brief Data that is private to a monitor technology
+	 *
+	 * Most channel drivers that implement CC monitors will have to
+	 * allocate data that the CC core does not care about but which
+	 * is vital to the operation of the monitor. This data is stored
+	 * in this pointer so that the channel driver may use it as
+	 * needed
+	 */
 	void *private_data;
 	AST_DLLIST_ENTRY(ast_cc_monitor) next;
 };
@@ -615,7 +627,7 @@
 	/*!
 	 * \brief Destroy private data on the monitor.
 	 *
-	 * \param monitor CC core monitor control.
+	 * \param private_data The private data pointer from the monitor.
 	 *
 	 * \details
 	 * Implementers of this callback are responsible for destroying
@@ -633,8 +645,7 @@
  * When arming the available timer from within a device monitor, you MUST
  * use this function as the callback for the scheduler.
  *
- * \param data The parent link of the monitor for which the available timer has been
- * armed.
+ * \param data A reference to the CC monitor on which the timer was running.
  */
 int ast_cc_available_timer_expire(const void *data);
 
@@ -672,6 +683,10 @@
  * Currently, this function is only used by chan_local.c, and probably
  * will never be used outside of that file, so you can safely ignore
  * this function, most likely.
+ *
+ * \param chan The channel whose CC datastore we wish to modify
+ * \param dialstring The dialstring we wish to set
+ * \retval void
  */
 void ast_cc_set_extension_dialstring(struct ast_channel *chan, const char * const dialstring);
 
@@ -845,7 +860,7 @@
 	unsigned int flags;
 	/*! Data specific to agent implementation */
 	void *private_data;
-	/*! The name of the interface which this agent
+	/*! The name of the device which this agent
 	 * represents/communicates with
 	 */
 	char device_name[1];
@@ -1070,11 +1085,6 @@
  * This function is called from ast_hangup if the caller is
  * eligible to be offered call completion service.
  *
- * XXX Since there is now an offer_cc callback for agents
- * and this actually does not call that callback, the
- * name of this function is quite confusing and should
- * change.
- *
  * \param caller_chan The calling channel
  * \retval -1 Error
  * \retval 0 Success
@@ -1216,7 +1226,8 @@
 
 /* END STATE CHANGE API */
 
-/* The following are all functions which are required due to the unique
+/*!
+ * The following are all functions which are required due to the unique
  * case where Asterisk is acting as the NT side of an ISDN PTMP
  * connection to the caller and as the TE side of an ISDN PTMP connection
  * to the callee. In such a case, there are several times where the
@@ -1584,9 +1595,7 @@
  * \since 1.8
  * \brief Initialize CCSS
  *
- * XXX This needs to be updated as more functionality is added.
- *
- * Creates ao2 container for pending CC offers.
+ * Performs startup routines necessary for CC operation.
  *
  * \retval 0 Success
  * \retval nonzero Failure


