Modifications all over the place, but mainly only to update Doxygen documentation

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@515 74dad513-b988-da41-8d7b-12977e46ad98

3 files changed, 106 insertions, 24 deletions

diff --git a/pjsip/include/pjsip-ua/sip_inv.h b/pjsip/include/pjsip-ua/sip_inv.h
index cdc8b8f9..e07ba79a 100644
--- a/pjsip/include/pjsip-ua/sip_inv.h
+++ b/pjsip/include/pjsip-ua/sip_inv.h
@@ -19,21 +19,73 @@
 #ifndef __SIP_INVITE_SESSION_H__
 #define __SIP_INVITE_SESSION_H__
 
+/**
+ * @file sip_inv.h
+ * @brief INVITE sessions
+ */
+
+
 #include <pjsip/sip_dialog.h>
 #include <pjmedia/sdp_neg.h>
 
 
+/**
+ * @defgroup PJSIP_HIGH_UA User Agent Library
+ * @ingroup PJSIP
+ * @brief Mid-level User Agent Library.
+ *
+ * This is the high level user agent library, which consists of:
+ *  - @ref PJSIP_INV, to encapsulate INVITE sessions and SDP
+ *    negotiation in the session,
+ *  - @ref PJSUA_REGC, high level client registration API, and
+ *  - @ref PJSUA_XFER.
+ *
+ * More detailed information is explained in
+ * <A HREF="/docs.htm">PJSIP Developer's Guide</A>
+ * PDF document, and readers are encouraged to read the document to
+ * get the concept behind dialog, dialog usages, and INVITE sessions.
+ *
+ * The User Agent Library is implemented in <b>pjsip-ua</b> static
+ * library.
+ */
+
+/**
+ * @defgroup PJSIP_INV INVITE Session
+ * @ingroup PJSIP_HIGH_UA
+ * @brief Provides INVITE session management.
+ * @{
+ *
+ * The INVITE session uses the @ref PJSIP_DIALOG framework to manage
+ * the underlying dialog, and is one type of usages that can use
+ * a particular dialog instance (other usages are event subscription,
+ * discussed in @ref PJSIP_EVENT_NOT). The INVITE session manages
+ * the life-time of the session, and also manages the SDP negotiation.
+ *
+ * Application must link with  <b>pjsip-ua</b> static library to use this API.
+ *
+ * More detailed information is explained in
+ * <A HREF="/docs.htm">PJSIP Developer's Guide</A>
+ * PDF document, and readers are encouraged to read the document to
+ * get the concept behind dialog, dialog usages, and INVITE sessions.
+ *
+ * The INVITE session does NOT manage media. If application wants to
+ * use API that encapsulates both signaling and media in a very easy
+ * to use API, it can use @ref PJSUA_LIB for this purpose.
+ */
+
 PJ_BEGIN_DECL
 
 
-typedef enum pjsip_inv_state pjsip_inv_state;
+/**
+ * @see pjsip_inv_session
+ */
 typedef struct pjsip_inv_session pjsip_inv_session;
-typedef struct pjsip_inv_callback pjsip_inv_callback;
+
 
 /**
  * This enumeration describes invite session state.
  */
-enum pjsip_inv_state
+typedef enum pjsip_inv_state
 {
     PJSIP_INV_STATE_NULL,	    /**< Before INVITE is sent or received  */
     PJSIP_INV_STATE_CALLING,	    /**< After INVITE is sent		    */
@@ -42,14 +94,14 @@ enum pjsip_inv_state
     PJSIP_INV_STATE_CONNECTING,	    /**< After 2xx is sent/received.	    */
     PJSIP_INV_STATE_CONFIRMED,	    /**< After ACK is sent/received.	    */
     PJSIP_INV_STATE_DISCONNECTED,   /**< Session is terminated.		    */
-};
+} pjsip_inv_state;
 
 /**
  * This structure contains callbacks to be registered by application to 
  * receieve notifications from the framework about various events in
  * the invite session.
  */
-struct pjsip_inv_callback
+typedef struct pjsip_inv_callback
 {
     /**
      * This callback is called when the invite sesion state has changed. 
@@ -118,7 +170,9 @@ struct pjsip_inv_callback
      */
     void (*on_media_update)(pjsip_inv_session *inv_ses, 
 			    pj_status_t status);
-};
+
+} pjsip_inv_callback;
+
 
 
 /**
@@ -187,7 +241,7 @@ struct pjsip_inv_session
  * occurences of events in invite sessions.
  *
  * @param endpt		The endpoint instance.
- * @param callback	Callback structure.
+ * @param cb		Callback structure.
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
  */
@@ -310,7 +364,7 @@ PJ_DECL(pj_status_t) pjsip_inv_verify_request(	pjsip_rx_data *rdata,
  *			in rdata. The invite session needs to inspect the 
  *			received request to see if the request contains 
  *			features that it supports.
- * @param sdp		If application has determined its media capability, 
+ * @param local_sdp	If application has determined its media capability, 
  *			it can specify this capability in this argument. 
  *			If SDP is received in the initial INVITE, the UAS 
  *			capability specified in this argument doesn't have to
@@ -563,6 +617,9 @@ PJ_DECL(const char *) pjsip_inv_state_name(pjsip_inv_state state);
 
 PJ_END_DECL
 
+/**
+ * @}
+ */
 
 
 #endif	/* __SIP_INVITE_SESSION_H__ */
diff --git a/pjsip/include/pjsip-ua/sip_regc.h b/pjsip/include/pjsip-ua/sip_regc.h
index d86c330e..a071fcc1 100644
--- a/pjsip/include/pjsip-ua/sip_regc.h
+++ b/pjsip/include/pjsip-ua/sip_regc.h
@@ -26,18 +26,22 @@
 
 #include <pjsip/sip_types.h>
 #include <pjsip/sip_auth.h>
-//#include <pjsip/sip_ua.h>
 
-PJ_BEGIN_DECL
 
 /**
- * @defgroup PJSUA_REGC SIP Registration Client
- * @ingroup PJSUA
+ * @defgroup PJSUA_REGC Client Registration
+ * @ingroup PJSIP_HIGH_UA
+ * @brief High Layer API for performing client registration.
  * @{
- * \brief
- *   API for performing registration for user agent.
+ *
+ * This provides API for performing client registration. Application must
+ * link with  <b>pjsip-ua</b> static library to use this API.
+
  */
 
+
+PJ_BEGIN_DECL
+
 /** Typedef for client registration data. */
 typedef struct pjsip_regc pjsip_regc;
 
@@ -56,15 +60,15 @@ typedef struct pjsip_regc pjsip_regc;
  */
 struct pjsip_regc_cbparam
 {
-    pjsip_regc		*regc;
-    void		*token;
-    int			 code;
-    pj_status_t		 status;
-    pj_str_t		 reason;
-    pjsip_rx_data	*rdata;
-    int			 contact_cnt;
-    int			 expiration;
-    pjsip_contact_hdr	*contact[PJSIP_REGC_MAX_CONTACT];
+    pjsip_regc		*regc;	    /**< Client registration structure.	    */
+    void		*token;	    /**< Arbitrary token.		    */
+    pj_status_t		 status;    /**< Error status.			    */
+    int			 code;	    /**< SIP status code received.	    */
+    pj_str_t		 reason;    /**< SIP reason phrase received.	    */
+    pjsip_rx_data	*rdata;	    /**< The complete received response.    */
+    int			 expiration;/**< Next expiration interval.	    */
+    int			 contact_cnt;/**<Number of contacts in response.    */
+    pjsip_contact_hdr	*contact[PJSIP_REGC_MAX_CONTACT]; /**< Contacts.    */
 };
 
 
@@ -149,6 +153,7 @@ PJ_DECL(pj_pool_t*) pjsip_regc_get_pool(pjsip_regc *regc);
  * perform the registration.
  *
  * @param regc	    The client registration structure.
+ * @param srv_url   Server URL.
  * @param from_url  The person performing the registration, must be a SIP URL type.
  * @param to_url    The address of record for which the registration is targetd, must
  *		    be a SIP/SIPS URL.
@@ -259,4 +264,8 @@ PJ_DECL(pj_status_t) pjsip_regc_send(pjsip_regc *regc, pjsip_tx_data *tdata);
 
 PJ_END_DECL
 
+/**
+ * @}
+ */
+
 #endif	/* __PJSIP_REG_H__ */
diff --git a/pjsip/include/pjsip-ua/sip_xfer.h b/pjsip/include/pjsip-ua/sip_xfer.h
index 16eb1956..56809141 100644
--- a/pjsip/include/pjsip-ua/sip_xfer.h
+++ b/pjsip/include/pjsip-ua/sip_xfer.h
@@ -28,6 +28,19 @@
 #include <pjsip-simple/evsub.h>
 #include <pjsip/sip_msg.h>
 
+/**
+ * @defgroup PJSUA_XFER Call Transfer
+ * @ingroup PJSIP_HIGH_UA
+ * @brief Provides call transfer functionality.
+ * @{
+ *
+ * This implements call transfer functionality to INVITE sessions. The call
+ * transfer functionality uses SIP Event Subscription framework for
+ * managing call transfer status.
+ *
+ * Application must link with <b>pjsip-ua</b> AND <b>pjsip-simple</b> static
+ * libraries to use call transfer functionality.
+ */
 
 
 PJ_BEGIN_DECL
@@ -168,8 +181,11 @@ PJ_DECL(pj_status_t) pjsip_xfer_send_request( pjsip_evsub *sub,
 					      pjsip_tx_data *tdata);
 
 
-
 PJ_END_DECL
 
+/**
+ * @}
+ */
+
 #endif	/* __PJSIP_XFER_H__ */