Part of ticket #780: enhance the PJNATH doxygen documentation

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

14 files changed, 351 insertions, 291 deletions

diff --git a/pjnath/include/pjnath/config.h b/pjnath/include/pjnath/config.h
index f418da1f..f9552721 100644
--- a/pjnath/include/pjnath/config.h
+++ b/pjnath/include/pjnath/config.h
@@ -29,8 +29,9 @@
 #include <pj/types.h>
 
 /**
- * @defgroup PJNATH_CONFIG Configuration
+ * @defgroup PJNATH_CONFIG Compile-time configurations
  * @brief Various compile time settings
+ * @ingroup PJNATH_STUN_BASE
  * @{
  */
 
diff --git a/pjnath/include/pjnath/errno.h b/pjnath/include/pjnath/errno.h
index 719ba412..e17f9460 100644
--- a/pjnath/include/pjnath/errno.h
+++ b/pjnath/include/pjnath/errno.h
@@ -30,6 +30,7 @@
 /**
  * @defgroup PJNATH_ERROR NAT Helper Library Error Codes
  * @brief PJNATH specific error code constants
+ * @ingroup PJNATH_STUN_BASE
  * @{
  */
 
diff --git a/pjnath/include/pjnath/ice_session.h b/pjnath/include/pjnath/ice_session.h
index aaba2511..18f7ffd6 100644
--- a/pjnath/include/pjnath/ice_session.h
+++ b/pjnath/include/pjnath/ice_session.h
@@ -30,19 +30,11 @@
 #include <pj/sock.h>
 #include <pj/timer.h>
 
-/**
- * @defgroup PJNATH_ICE Interactive Connectivity Establishment (ICE)
- * @brief Interactive Connectivity Establishment (ICE)
- */
-
-
 PJ_BEGIN_DECL
 
 
 /**
- * @defgroup PJNATH_ICE_SESSION ICE Session
- * @brief Transport Independent ICE Session
- * @ingroup PJNATH_ICE
+ * @addtogroup PJNATH_ICE_SESSION
  * @{
  *
  * This module describes #pj_ice_sess, a transport independent ICE session,
@@ -204,16 +196,22 @@ typedef struct pj_ice_sess_comp
  */
 typedef struct pj_ice_msg_data
 {
+    /** Transport ID for this message */
     unsigned	transport_id;
+
+    /** Flag to indicate whether data.req contains data */
     pj_bool_t	has_req_data;
 
+    /** The data */
     union data {
+	/** Request data */
 	struct request_data {
-	    pj_ice_sess		    *ice;
-	    pj_ice_sess_checklist   *clist;
-	    unsigned		     ckid;
+	    pj_ice_sess		    *ice;   /**< ICE session	*/
+	    pj_ice_sess_checklist   *clist; /**< Checklist	*/
+	    unsigned		     ckid;  /**< Check ID	*/
 	} req;
     } data;
+
 } pj_ice_msg_data;
 
 
@@ -539,7 +537,7 @@ typedef enum pj_ice_sess_role
  */
 typedef struct pj_ice_rx_check
 {
-    PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check);
+    PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check); /**< Standard list     */
 
     unsigned		 comp_id;	/**< Component ID.		*/
     unsigned		 transport_id;	/**< Transport ID.		*/
@@ -600,7 +598,7 @@ struct pj_ice_sess
     unsigned		 rcand_cnt;		    /**< # of remote cand.  */
     pj_ice_sess_cand	 rcand[PJ_ICE_MAX_CAND];    /**< Array of cand.	    */
 
-    /* Array of transport datas */
+    /** Array of transport datas */
     pj_ice_msg_data	 tp_data[4];
 
     /* List of eearly checks */
@@ -612,7 +610,7 @@ struct pj_ice_sess
     /* Valid list */
     pj_ice_sess_checklist valid_list;		    /**< Valid list.	    */
     
-    /* Temporary buffer for misc stuffs to avoid using stack too much */
+    /** Temporary buffer for misc stuffs to avoid using stack too much */
     union {
     	char txt[128];
 	char errmsg[PJ_ERR_MSG_SIZE];
diff --git a/pjnath/include/pjnath/ice_strans.h b/pjnath/include/pjnath/ice_strans.h
index e28e8865..02397073 100644
--- a/pjnath/include/pjnath/ice_strans.h
+++ b/pjnath/include/pjnath/ice_strans.h
@@ -37,9 +37,7 @@ PJ_BEGIN_DECL
 
 
 /**
- * @defgroup PJNATH_ICE_STREAM_TRANSPORT ICE Stream Transport
- * @brief Transport for media streams using ICE
- * @ingroup PJNATH_ICE
+ * @addtogroup PJNATH_ICE_STREAM_TRANSPORT
  * @{
  *
  * This module describes ICE stream transport, as represented by #pj_ice_strans
@@ -53,6 +51,66 @@ PJ_BEGIN_DECL
  * \ref PJNATH_ICE_SESSION for performing connectivity checks among the.
  * various candidates of the transport addresses.
  *
+ *
+ * \section ice_strans_using_sec Using the ICE stream transport
+ *
+ * The steps below describe how to use ICE session:
+ *
+ *  - initialize a #pj_ice_strans_cfg structure. This contains various 
+ *    settings for the ICE stream transport, and among other things contains
+ *    the STUN and TURN settings.\n\n
+ *  - create the instance with #pj_ice_strans_create(). Among other things,
+ *    the function needs the following arguments:
+ *	- the #pj_ice_strans_cfg structure for the main configurations
+ *	- number of components to be supported
+ *	- instance of #pj_ice_strans_cb structure to report callbacks to
+ *	  application.\n\n
+ *  - while the #pj_ice_strans_create() call completes immediately, the
+ *    initialization will be running in the background to gather the 
+ *    candidates (for example STUN and TURN candidates, if they are enabled
+ *    in the #pj_ice_strans_cfg setting). Application will be notified when
+ *    the initialization completes in the \a on_ice_complete callback of
+ *    the #pj_ice_strans_cb structure (the \a op argument of this callback
+ *    will be PJ_ICE_STRANS_OP_INIT).\n\n
+ *  - when media stream is to be started (for example, a call is to be 
+ *    started), create an ICE session by calling #pj_ice_strans_init_ice().\n\n
+ *  - the application now typically will need to communicate local ICE
+ *    information to remote host. It can achieve this by using the following
+ *    functions to query local ICE information:
+ *	- #pj_ice_strans_get_ufrag_pwd()
+ *	- #pj_ice_strans_enum_cands()
+ *	- #pj_ice_strans_get_def_cand()\n
+ *    The application may need to encode the above information as SDP.\n\n
+ *  - when the application receives remote ICE information (for example, from
+ *    the SDP received from remote), it can now start ICE negotiation, by
+ *    calling #pj_ice_strans_start_ice(). This function requires some
+ *    information about remote ICE agent such as remote ICE username fragment
+ *    and password as well as array of remote candidates.\n\n
+ *  - note that the PJNATH library does not work with SDP; application would
+ *    need to encode and parse the SDP itself.\n\n
+ *  - once ICE negotiation has been started, application will be notified
+ *    about the completion in the \a on_ice_complete() callback of the
+ *    #pj_ice_strans_cb.\n\n
+ *  - at any time, application may send or receive data. However the ICE
+ *    stream transport may not be able to send it depending on its current
+ *    state. Before ICE negotiation is started, the data will be sent using
+ *    default candidate of the component. After negotiation is completed,
+ *    data will be sent using the candidate from the successful/nominated
+ *    pair. The ICE stream transport may not be able to send data while 
+ *    negotiation is in progress.\n\n
+ *  - application sends data by using #pj_ice_strans_sendto(). Incoming
+ *    data will be reported in \a on_rx_data() callback of the
+ *    #pj_ice_strans_cb.\n\n
+ *  - once the media session has finished (e.g. user hangs up the call),
+ *    destroy the ICE session with #pj_ice_strans_stop_ice().\n\n
+ *  - at this point, application may destroy the ICE stream transport itself,
+ *    or let it run so that it can be reused to create other ICE session.
+ *    The benefit of letting the ICE stream transport alive (without any
+ *    session active) is to avoid delay with the initialization, howerver
+ *    keeping the transport alive means the transport needs to keep the
+ *    STUN binding open by using keep-alive and also TURN allocation alive,
+ *    and this will consume power which is an important issue for mobile
+ *    applications.\n\n
  */
 
 /** Forward declaration for ICE stream transport. */
diff --git a/pjnath/include/pjnath/nat_detect.h b/pjnath/include/pjnath/nat_detect.h
index a73781a7..40c88a93 100644
--- a/pjnath/include/pjnath/nat_detect.h
+++ b/pjnath/include/pjnath/nat_detect.h
@@ -33,6 +33,7 @@ PJ_BEGIN_DECL
 /**
  * @defgroup PJNATH_NAT_DETECT NAT Classification/Detection Tool
  * @brief NAT Classification/Detection Tool
+ * @ingroup PJNATH
  * @{
  *
  * This module provides one function to perform NAT classification and
diff --git a/pjnath/include/pjnath/stun_auth.h b/pjnath/include/pjnath/stun_auth.h
index c1aea038..5befb5e0 100644
--- a/pjnath/include/pjnath/stun_auth.h
+++ b/pjnath/include/pjnath/stun_auth.h
@@ -35,7 +35,7 @@ PJ_BEGIN_DECL
 /**
  * @defgroup PJNATH_STUN_AUTH STUN Authentication
  * @brief STUN authentication helper
- * @ingroup PJNATH_STUN
+ * @ingroup PJNATH_STUN_BASE
  * @{
  */
 
diff --git a/pjnath/include/pjnath/stun_config.h b/pjnath/include/pjnath/stun_config.h
index 7025db61..c4721471 100644
--- a/pjnath/include/pjnath/stun_config.h
+++ b/pjnath/include/pjnath/stun_config.h
@@ -38,7 +38,7 @@ PJ_BEGIN_DECL
 /**
  * @defgroup PJNATH_STUN_CONFIG STUN Config
  * @brief STUN config
- * @ingroup PJNATH_STUN
+ * @ingroup PJNATH_STUN_BASE
  * @{
  */
 
diff --git a/pjnath/include/pjnath/stun_msg.h b/pjnath/include/pjnath/stun_msg.h
index cf183d02..57fc38c4 100644
--- a/pjnath/include/pjnath/stun_msg.h
+++ b/pjnath/include/pjnath/stun_msg.h
@@ -35,7 +35,7 @@ PJ_BEGIN_DECL
 /* **************************************************************************/
 /**
  * @defgroup PJNATH_STUN_MSG STUN Message Representation and Parsing
- * @ingroup PJNATH_STUN
+ * @ingroup PJNATH_STUN_BASE
  * @brief Low-level representation and parsing of STUN messages.
  * @{
  */
diff --git a/pjnath/include/pjnath/stun_session.h b/pjnath/include/pjnath/stun_session.h
index 714cbf9e..2a6fd022 100644
--- a/pjnath/include/pjnath/stun_session.h
+++ b/pjnath/include/pjnath/stun_session.h
@@ -37,10 +37,130 @@ PJ_BEGIN_DECL
 
 /* **************************************************************************/
 /**
- * @defgroup PJNATH_STUN_SESSION STUN Client/Server Session
- * @brief STUN client and server session
- * @ingroup PJNATH_STUN
+ * @addtogroup PJNATH_STUN_SESSION
  * @{
+ *
+ * This is is a transport-independent object to manage a client or server 
+ * STUN session. It has the following features:
+ * 
+ *  - <b>transport independent</b>:\n
+ *    the object does not have it's own socket, but rather it provides
+ *    functions and callbacks to send and receive packets. This way the
+ *    object can be used by different transport types (e.g. UDP, TCP, 
+ *    TLS, etc.) as well as better integration to application which
+ *    already has its own means to send and receive packets.
+ * 
+ *  - <b>authentication management</b>:\n
+ *    the object manages STUN authentication throughout the lifetime of
+ *    the session. For client sessions, once it's given a credential to
+ *    authenticate itself with the server, the object will automatically
+ *    add authentication info (the MESSAGE-INTEGRITY) to the request as
+ *    well as authenticate the response. It will also handle long-term 
+ *    authentication challenges, including handling of nonce expiration,
+ *    and retry the request automatically. For server sessions, it can 
+ *    be configured to authenticate incoming requests automatically.
+ *  
+ *  - <b>static or dynamic credential</b>:\n
+ *    application may specify static or dynamic credential to be used by
+ *    the STUN session. Static credential means a static combination of
+ *    username and password (and these cannot change during the session
+ *    duration), while dynamic credential provides callback to ask the
+ *    application about which username/password to use everytime
+ *    authentication is about to be performed.
+ *    
+ *  - <b>client transaction management</b>:\n
+ *    outgoing requests may be sent with a STUN transaction for reliability,
+ *    and the object will manage the transaction internally (including
+ *    performing retransmissions). Application will be notified about the
+ *    result of the request when the response arrives (or the transaction
+ *    times out). When the request is challenged with authentication, the
+ *    object will retry the request with new authentication info, and 
+ *    application will be notified about the final result of this request.
+ * 
+ *  - <b>server transaction management</b>:\n
+ *    application may ask response to incoming requests to be cached by
+ *    the object, and in this case the object will check for cached
+ *    response everytime request is received. The cached response will be
+ *    deleted once a timer expires.
+ *
+ * \section using_stun_sess_sec Using the STUN session
+ *
+ * The following steps describes how to use the STUN session:
+ *
+ *  - <b>create the object configuration</b>:\n
+ *    The #pj_stun_config contains the configuration to create the STUN
+ *    session, such as the timer heap to register internal timers and
+ *    various STUN timeout values. You can initialize this structure by
+ *    calling #pj_stun_config_init()
+ *
+ *  - <b>create the STUN session</b>:\n
+ *    by calling #pj_stun_session_create(). Among other things, this
+ *    function requires the instance of #pj_stun_config and also 
+ *    #pj_stun_session_cb structure which stores callbacks to send
+ *    outgoing packets as well as to notify application about incoming
+ *    STUN requests, responses, and indicates and other events.
+ *
+ *  - <b>configure credential:</b>\n
+ *    if authentication is required for the session, configure the
+ *    credential with #pj_stun_session_set_credential()
+ *
+ *  - <b>configuring other settings:</b>\n
+ *    several APIs are provided to configure the behavior of the STUN
+ *    session (for example, to set the SOFTWARE attribute value, controls
+ *    the logging behavior, fine tune the mutex locking, etc.). Please see
+ *    the API reference for more info.
+ *
+ *  - <b>creating outgoing STUN requests or indications:</b>\n
+ *    create the STUN message by using #pj_stun_session_create_req() or
+ *    #pj_stun_session_create_ind(). This will create a transmit data
+ *    buffer containing a blank STUN request or indication. You will then
+ *    typically need to add STUN attributes that are relevant to the
+ *    request or indication, but note that some default attributes will
+ *    be added by the session later when the message is sent (such as
+ *    SOFTWARE attribute and attributes related to authentication).
+ *    The message is now ready to be sent.
+ *
+ *  - <b>sending outgoing message:</b>\n
+ *    use #pj_stun_session_send_msg() to send outgoing STUN messages (this
+ *    includes STUN requests, indications, and responses). The function has
+ *    options whether to retransmit the request (for non reliable transports)
+ *    or to cache the response if we're sending response. This function in 
+ *    turn will call the \a on_send_msg() callback of #pj_stun_session_cb 
+ *    to request the application to send the packet.
+ *
+ *  - <b>handling incoming packet:</b>\n
+ *    call #pj_stun_session_on_rx_pkt() everytime the application receives
+ *    a STUN packet. This function will decode the packet and process the
+ *    packet according to the message, and normally this will cause one
+ *    of the callback in the #pj_stun_session_cb to be called to notify
+ *    the application about the event.
+ *
+ *  - <b>handling incoming requests:</b>\n
+ *    incoming requests are notified to application in the \a on_rx_request
+ *    callback of the #pj_stun_session_cb. If authentication is enabled in
+ *    the session, the application will only receive this callback after
+ *    the incoming request has been authenticated (if the authentication
+ *    fails, the session would respond automatically with 401 error and
+ *    the callback will not be called). Application now must create and
+ *    send response for this request.
+ *
+ *  - <b>creating and sending response:</b>\n
+ *    create the STUN response with #pj_stun_session_create_res(). This will
+ *    create a transmit data buffer containing a blank STUN response. You 
+ *    will then typically need to add STUN attributes that are relevant to
+ *    the response, but note that some default attributes will
+ *    be added by the session later when the message is sent (such as
+ *    SOFTWARE attribute and attributes related to authentication).
+ *    The message is now ready to be sent. Use #pj_stun_session_send_msg()
+ *    (as explained above) to send the response.
+ *
+ *  - <b>convenient way to send response:</b>\n
+ *    the #pj_stun_session_respond() is provided as a convenient way to
+ *    create and send simple STUN responses, such as error responses.
+ *    
+ *  - <b>destroying the session:</b>\n
+ *    once the session is done, use #pj_stun_session_destroy() to destroy
+ *    the session.
  */
 
 
diff --git a/pjnath/include/pjnath/stun_sock.h b/pjnath/include/pjnath/stun_sock.h
index 5dcaad2b..b196b325 100644
--- a/pjnath/include/pjnath/stun_sock.h
+++ b/pjnath/include/pjnath/stun_sock.h
@@ -34,16 +34,24 @@ PJ_BEGIN_DECL
 
 
 /**
- * @defgroup PJNATH_STUN_SOCK STUN aware socket transport
- * @brief STUN aware socket transport
- * @ingroup PJNATH_STUN
+ * @addtogroup PJNATH_STUN_SOCK
  * @{
  *
  * The STUN transport provides asynchronous UDP like socket transport
- * with the additional capability to query the publicly mapped transport
- * address (using STUN resolution), to refresh the NAT binding, and to
- * demultiplex internal STUN messages from application data (the 
- * application data may be a STUN message as well).
+ * with the additional STUN capability. It has the following features:
+ *
+ *  - API to send and receive UDP packets
+ *
+ *  - multiplex STUN and non-STUN incoming packets and distinguish between
+ *    STUN responses that belong to internal requests with application data
+ *    (the application data may be STUN packets as well)
+ *
+ *  - DNS SRV resolution to the STUN server (if wanted), along with fallback
+ *    to DNS A resolution if SRV record is not found.
+ *
+ *  - STUN keep-alive maintenance, and handle changes to the mapped address
+ *    (when the NAT binding changes)
+ *
  */
 
 /**
@@ -275,7 +283,7 @@ PJ_DECL(void) pj_stun_sock_cfg_default(pj_stun_sock_cfg *cfg);
  *			this transport.
  * @param p_sock	Pointer to receive the created transport instance.
  *
- * @restun		PJ_SUCCESS if the operation has been successful,
+ * @return		PJ_SUCCESS if the operation has been successful,
  *			or the appropriate error code on failure.
  */
 PJ_DECL(pj_status_t) pj_stun_sock_create(pj_stun_config *stun_cfg,
@@ -327,7 +335,7 @@ PJ_DECL(pj_status_t) pj_stun_sock_start(pj_stun_sock *stun_sock,
  *
  * @param sock		The STUN transport socket.
  *
- * @restun		PJ_SUCCESS if the operation has been successful,
+ * @return		PJ_SUCCESS if the operation has been successful,
  *			or the appropriate error code on failure.
  */
 PJ_DECL(pj_status_t) pj_stun_sock_destroy(pj_stun_sock *sock);
@@ -340,7 +348,7 @@ PJ_DECL(pj_status_t) pj_stun_sock_destroy(pj_stun_sock *sock);
  * @param stun_sock	The STUN transport instance.
  * @param user_data	Arbitrary data.
  *
- * @restun		PJ_SUCCESS if the operation has been successful,
+ * @return		PJ_SUCCESS if the operation has been successful,
  *			or the appropriate error code on failure.
  */
 PJ_DECL(pj_status_t) pj_stun_sock_set_user_data(pj_stun_sock *stun_sock,
@@ -352,7 +360,7 @@ PJ_DECL(pj_status_t) pj_stun_sock_set_user_data(pj_stun_sock *stun_sock,
  *
  * @param stun_sock	The STUN transport instance.
  *
- * @restun		The user/application data.
+ * @return		The user/application data.
  */
 PJ_DECL(void*) pj_stun_sock_get_user_data(pj_stun_sock *stun_sock);
 
@@ -364,7 +372,7 @@ PJ_DECL(void*) pj_stun_sock_get_user_data(pj_stun_sock *stun_sock);
  * @param stun_sock	The STUN transport instance.
  * @param info		Pointer to be filled with STUN transport info.
  *
- * @restun		PJ_SUCCESS if the operation has been successful,
+ * @return		PJ_SUCCESS if the operation has been successful,
  *			or the appropriate error code on failure.
  */
 PJ_DECL(pj_status_t) pj_stun_sock_get_info(pj_stun_sock *stun_sock,
@@ -376,7 +384,7 @@ PJ_DECL(pj_status_t) pj_stun_sock_get_info(pj_stun_sock *stun_sock,
  * asynchronously and in this case \a on_data_sent() will be called.
  *
  * @param stun_sock	The STUN transport instance.
- * @param op_key	Optional send key for sending the packet down to
+ * @param send_key	Optional send key for sending the packet down to
  *			the ioqueue. This value will be given back to
  *			\a on_data_sent() callback
  * @param pkt		The data/packet to be sent to peer.
diff --git a/pjnath/include/pjnath/stun_transaction.h b/pjnath/include/pjnath/stun_transaction.h
index 12ff03fa..d73e8146 100644
--- a/pjnath/include/pjnath/stun_transaction.h
+++ b/pjnath/include/pjnath/stun_transaction.h
@@ -36,7 +36,7 @@ PJ_BEGIN_DECL
 /**
  * @defgroup PJNATH_STUN_TRANSACTION STUN Client Transaction
  * @brief STUN client transaction
- * @ingroup PJNATH_STUN
+ * @ingroup PJNATH_STUN_BASE
  * @{
  *
  The @ref PJNATH_STUN_TRANSACTION is used to manage outgoing STUN request,
diff --git a/pjnath/include/pjnath/turn_session.h b/pjnath/include/pjnath/turn_session.h
index 88cf1bfe..64f12787 100644
--- a/pjnath/include/pjnath/turn_session.h
+++ b/pjnath/include/pjnath/turn_session.h
@@ -30,25 +30,99 @@
 
 PJ_BEGIN_DECL
 
-/**
- * @defgroup PJNATH_TURN TURN Client Library
- */
-
 
 /* **************************************************************************/
 /**
- * @defgroup PJNATH_TURN_SESSION Transport independent TURN client session
- * @brief Transport independent TURN client session
- * @ingroup PJNATH_TURN
- * @{
- *
- * This module describes the transport independent TURN client session. This
- * interface is provided for implementors of a TURN client transport, and
- * application usually will want to use \ref PJNATH_TURN_SOCK instead.
- *
- * The transport independent TURN client session is created to facilitate
- * the creation of different types of transports between the client and the
- * TURN server.
+@addtogroup PJNATH_TURN_SESSION
+@{
+
+The \ref PJNATH_TURN_SESSION is a transport-independent object to
+manage a client TURN session. It contains the core logic for manage
+the TURN client session as listed in \ref turn_op_sec, but
+in transport-independent manner (i.e. it doesn't have a socket), so
+that developer can integrate TURN client functionality into existing
+framework that already has its own means to send and receive data,
+or to support new transport types to TURN, such as TLS.
+
+
+\section turn_sess_using_sec Using the TURN session
+
+These steps describes how to use the TURN session:
+
+ - <b>Creating the session</b>:\n
+   use #pj_turn_session_create() to create the session. 
+
+ - <b>Configuring credential</b>:\n
+   all TURN operations requires the use of authentication (it uses STUN 
+   long term autentication method). Use #pj_turn_session_set_credential()
+   to configure the TURN credential to be used by the session.
+
+ - <b>Configuring server</b>:\n
+   application must call #pj_turn_session_set_server() before it can send
+   Allocate request (with pj_turn_session_alloc()). This function will
+   resolve the TURN server using DNS SRV resolution if the \a resolver
+   is set. The server resolution process will complete asynchronously,
+   and application will be notified in \a on_state() callback of the 
+   #pj_turn_session_cb structurewith the session state set to 
+   PJ_TURN_STATE_RESOLVED.
+
+ - <b>Creating allocation</b>:\n
+   create one "relay port" (or called <b>relayed-transport-address</b>
+   in TURN terminology) in the TURN server by using #pj_turn_session_alloc().
+   This will send Allocate request to the server. This function will complete
+   immediately, and application will be notified about the allocation
+   result in the \a on_state() callback of the #pj_turn_session_cb structure.
+
+ - <b>Getting the allocation result</b>:\n
+   if allocation is successful, the session state will progress to
+   \a PJ_TURN_STATE_READY, otherwise the state will be 
+   \a PJ_TURN_STATE_DEALLOCATED or higher. Session state progression is
+   reported in the \a on_state() callback of the #pj_turn_session_cb 
+   structure. On successful allocation, application may retrieve the
+   allocation info by calling #pj_turn_session_get_info().
+
+ - <b>Sending data through the relay</b>.\n
+   Once allocation has been created, client may send data to any remote 
+   endpoints (called peers in TURN terminology) via the "relay port". It does
+   so by calling #pj_turn_session_sendto(), giving the peer address 
+   in the function argument. But note that at this point peers are not allowed
+   to send data towards the client (via the "relay port") before permission is
+   installed for that peer.
+
+ - <b>Creating permissions</b>.\n
+   Permission needs to be created in the TURN server so that a peer can send 
+   data to the client via the relay port (a peer in this case is identified by
+   its IP address). Without this, when the TURN server receives data from the
+   peer in the "relay port", it will drop this data. Create the permission by
+   calling #pj_turn_session_set_perm(), specifying the peer IP address in the
+   argument (the port part of the address is ignored). More than one IP 
+   addresses may be specified.
+
+ - <b>Receiving data from peers</b>.\n
+   Once permission has been installed for the peer, any data received by the 
+   TURN server (from that peer) in the "relay port" will be relayed back to 
+   client by the server, and application will be notified via \a on_rx_data
+   callback of the #pj_turn_session_cb.
+
+ - <b>Using ChannelData</b>.\n
+   TURN provides optimized framing to the data by using ChannelData 
+   packetization. The client activates this format for the specified peer by
+   calling #pj_turn_session_bind_channel(). Data sent or received to/for
+   this peer will then use ChannelData format instead of Send or Data 
+   Indications.
+
+ - <b>Refreshing the allocation, permissions, and channel bindings</b>.\n
+   Allocations, permissions, and channel bindings will be refreshed by the
+   session automatically when they about to expire.
+
+ - <b>Destroying the allocation</b>.\n
+   Once the "relay port" is no longer needed, client destroys the allocation
+   by calling #pj_turn_session_shutdown(). This function will return
+   immediately, and application will be notified about the deallocation
+   result in the \a on_state() callback of the #pj_turn_session_cb structure.
+   Once the state has reached PJ_TURN_STATE_DESTROYING, application must
+   assume that the session will be destroyed shortly after.
+
  */
 
 /** 
diff --git a/pjnath/include/pjnath/turn_sock.h b/pjnath/include/pjnath/turn_sock.h
index e0931ab9..f6776b83 100644
--- a/pjnath/include/pjnath/turn_sock.h
+++ b/pjnath/include/pjnath/turn_sock.h
@@ -32,17 +32,26 @@ PJ_BEGIN_DECL
 
 /* **************************************************************************/
 /**
- * @defgroup PJNATH_TURN_SOCK TURN client transport
- * @brief Client transport utilizing TURN relay
- * @ingroup PJNATH_TURN
- * @{
- *
- * The TURN relay client transport can be used to relay data from the client
- * to peer via a TURN relay. The application establishes TURN connection to
- * the TURN server using UDP or TCP as the transport, then creates a relay
- * address in the TURN server to be advertised to remote peer(s) as the 
- * transport address. When application sends data to a remote address via
- * this transport, the data will be sent via the TURN relay, and vice versa.
+@addtogroup PJNATH_TURN_SOCK
+@{
+
+This is a ready to use object for relaying application data via a TURN server,
+by managing all the operations in \ref turn_op_sec.
+
+\section turnsock_using_sec Using TURN transport
+
+This object provides a thin wrapper to the \ref PJNATH_TURN_SESSION, hence the
+API is very much the same (apart from the obvious difference in the names).
+Please see \ref PJNATH_TURN_SESSION for the documentation on how to use the
+session.
+
+\section turnsock_samples_sec Samples
+
+The \ref turn_client_sample is a sample application to use the
+\ref PJNATH_TURN_SOCK.
+
+Also see <b>\ref samples_page</b> for other samples.
+
  */
 
 
@@ -206,6 +215,21 @@ PJ_DECL(void) pj_turn_sock_set_log(pj_turn_sock *turn_sock,
 				   unsigned flags);
 
 /**
+ * Configure the SOFTWARE name to be sent in all STUN requests by the
+ * TURN session.
+ *
+ * @param turn_sock	The TURN transport instance.
+ * @param sw	    Software name string. If this argument is NULL or
+ *		    empty, the session will not include SOFTWARE attribute
+ *		    in STUN requests and responses.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_turn_sock_set_software_name(pj_turn_sock *turn_sock,
+						    const pj_str_t *sw);
+
+
+/**
  * Allocate a relay address/resource in the TURN server. This function
  * will resolve the TURN server using DNS SRV (if desired) and send TURN
  * \a Allocate request using the specified credential to allocate a relay
diff --git a/pjnath/include/pjnath/types.h b/pjnath/include/pjnath/types.h
index 0f857d00..c5837e65 100644
--- a/pjnath/include/pjnath/types.h
+++ b/pjnath/include/pjnath/types.h
@@ -72,230 +72,5 @@ PJ_END_DECL
  * @}
  */
 
-/* Doxygen documentation below: */
-
-/**
-
-@mainpage PJNATH - Open Source ICE, STUN, and TURN Library
-
-\n
-This is the documentation of PJNATH, an Open Source library providing
-NAT traversal helper functionalities by using standard based protocols
-such as STUN, TURN, and ICE.
-
-\n
-\n
-
-\section lib_comps Library Components
-
-\subsection comp_stun STUN
-
-Session Traversal Utilities (STUN, or previously known as Simple 
-Traversal of User Datagram Protocol (UDP) Through Network Address 
-Translators (NAT)s), is a lightweight protocol that serves as a tool for
-application protocols in dealing with NAT traversal. It allows a client
-to determine the IP address and port allocated to them by a NAT and to 
-keep NAT bindings open.
-
-This version of PJNATH implements the following STUN RFC:
-- <A HREF="http://www.ietf.org/rfc/rfc5389.txt"><B>RFC 5389</b></A>: 
-    Session Traversal Utilities for (NAT) (STUN),
-
-
-\subsection comp_turn TURN
-
-Traversal Using Relays around NAT (TURN) allows the host to control the
-operation of the relay and to exchange packets with its peers using the relay.
-
-Features:
- - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-13.txt">
-   <B>draft-ietf-behave-turn-13</B></A>: Obtaining Relay Addresses 
-   from Simple Traversal Underneath NAT (STUN)
- - DNS SRV resolution
- - Fallback to DNS A resolution if SRV record is not found
- - UDP and TCP connection to TURN server
- - automatic management of allocation refresh
-
-
-
-\subsection comp_ice ICE
-
-Interactive Connectivity Establishment (ICE) is a standard based 
-methodology for traversing Network Address Translator (NAT). This
-implementation is aimed to provide a usable and generic ICE transports
-for different types of application, including but not limited to
-the usage of ICE in SIP/SDP offer/answer.
-
-
-This version of PJNATH implements the following ICE draft:
- - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-19.txt">
-   <B>draft-ietf-mmusic-ice-19.txt</B></A> draft. The PJNATH ICE
-
-
-\subsection comp_natck NAT Classification Utility
-
-The PJNATH library also provides NAT classification utility as 
-described in <A HREF="http://www.ietf.org/rfc/rfc3489.txt">RFC 3489</A>.
-While the practice to detect the NAT type to assist NAT traversal
-has been deprecated in favor of ICE, the information may still be
-useful for troubleshooting purposes, hence the utility is provided.
-
-
-\n
-\n
-
-\section lib_org Library Organization
-
-The PJNATH library consists of many components with each providing
-specific functionality that may or may not be of the interests of 
-applications (or application developers). This section attempts to 
-give brief overview on the components provided by PJNATH.
-
-The PJNATH components from the highest layer to the lower layer are
-as follows.
-
-
-\n
-
-\subsection user_comp High-level Transport Objects
-
-PJNATH library provides some high-level objects that may be used
-by applications:
-
-
-\subsubsection stun_sock STUN Transport
-
-The \ref PJNATH_STUN_SOCK provides asynchronous UDP like socket transport
-with the additional capability to query the publicly mapped transport
-address (using STUN resolution), to refresh the NAT binding, and to
-demultiplex internal STUN messages from application data (the 
-application data may be a STUN message as well).
-
-
-\subsubsection turn_sock TURN Client Transport
-
-The \ref PJNATH_TURN_SOCK may be used by the application to send and
-receive data via TURN server. For more information please see the
-documentation of \ref PJNATH_TURN_SOCK.
-
-
-\subsubsection ice_strans ICE Stream Transport
-
-The \ref PJNATH_ICE_STREAM_TRANSPORT provides transport interface to
-send and receive data through connection that is negotiated
-with ICE protocol. The \ref PJNATH_ICE_STREAM_TRANSPORT naturally 
-contains both STUN Transport and \ref PJNATH_TURN_SOCK.
-
-The \ref PJNATH_ICE_STREAM_TRANSPORT interface is suitable for both
-SIP or non-SIP use. For SIP use, application may prefer to use the
-ICE media transport in PJMEDIA instead where it has been integrated
-with the SDP offer and answer mechanism.
-
-
-\subsubsection natck NAT Classification Utility
-
-PJNATH also provides \a PJNATH_NAT_DETECT to assist troubleshooting
-of problems related to NAT traversal.
-
-
-
-\n
-
-
-\subsection sessions Transport Independent Sessions Layer
-
-Right below the high level transports objects are the transport
-independent sessions. These sessions don't have access to sockets,
-so higher level objects (such as transports) must give incoming
-packets to the sessions and provide callback to be called by
-sessions to send outgoing packets.
-
-
-\subsubsection ice_sess ICE Session
-
-The \ref PJNATH_ICE_SESSION is used by the \ref PJNATH_ICE_STREAM_TRANSPORT
-and contains the actual logic of the ICE negotiation.
-
-
-\subsubsection turn_sess TURN Session
-
-The \ref PJNATH_TURN_SESSION is used by the \ref PJNATH_TURN_SOCK
-and it contains TURN protocol logic. Implementors may implement
-other types of TURN client connection (such as TURN TLS client)
-by utilizing this session.
-
-
-\subsubsection stun_sess STUN Session
-
-The \ref PJNATH_STUN_SESSION manages STUN message exchange between
-a client and server (or vice versa). It manages \ref PJNATH_STUN_TRANSACTION
-for sending or receiving requests and \ref PJNATH_STUN_AUTH for both
-both incoming and outgoing STUN messages. 
-
-The \ref PJNATH_STUN_SESSION is naturally used by the \ref PJNATH_TURN_SESSION
-and \ref PJNATH_ICE_SESSION
-
-
-\n
-
-\subsection stun_tsx STUN Transaction Layer
-
-The \ref PJNATH_STUN_TRANSACTION is a thin layer to manage retransmission
-of STUN requests.
-
-
-\n
-
-
-\subsection stun_msg STUN Messaging Layer
-
-At the very bottom of the PJNATH components is the \ref PJNATH_STUN_MSG
-layer. The API contains various representation of STUN messaging components
-and it provides API to encode and decode STUN messages.
-
-
-
-\n
-\n
-
-\section class_dia Class Diagram
-
-
-The following class diagram shows the interactions between objects in
-PJNATH:
-
-\image html UML-class-diagram.png "Class Diagram"
-\image latex UML-class-diagram.png "Class Diagram"
-
-
-
-\n
-\n
-
-\section samples Sample Applications
-
-
-Some sample applications have been provided with PJNATH, and it's available
-under <tt>pjnath/src</tt> directory:
-
-   - <b>pjturn-client</b>: this is a stand-alone, console based TURN client
-     application to be used as a demonstration for PJNATH TURN client 
-     transport API and for simple testing against TURN server implementations.
-     The client supports both UDP and TCP connection to the TURN server.
-
-   - <b>pjturn-srv</b>: this is a simple TURN server to be used for testing
-     purposes. It supports both UDP and TCP connections to the clients.
-
-
-*/
-
-/**
- * @defgroup PJNATH_STUN STUN Library
- * @brief Open source STUN library
- *
- * This module contains implementation of STUN library in PJNATH -
- * the open source NAT helper containing STUN and ICE.
- */
-
 #endif	/* __PJNATH_TYPES_H__ */