Index: pjproject/trunk/pjnath/include/pjnath/ice_session.h
===================================================================
--- pjproject/trunk/pjnath/include/pjnath/ice_session.h	(revision 1486)
+++ pjproject/trunk/pjnath/include/pjnath/ice_session.h	(revision 1487)
@@ -46,4 +46,6 @@
  * This module describes #pj_ice_sess, a transport independent ICE session,
  * part of PJNATH - the Open Source NAT helper library.
+ *
+ * \section pj_ice_sess_sec ICE Session
  *
  * An ICE session, represented by #pj_ice_sess structure, is the lowest 
@@ -63,4 +65,65 @@
  * For higher abstraction of ICE where transport is included, please 
  * see \ref PJNATH_ICE_STREAM_TRANSPORT.
+ *
+ * \subsection pj_ice_sess_using_sec Using The ICE Session
+ *
+ * The steps below describe how to use ICE session. Alternatively application
+ * can use the higher level ICE API, \ref PJNATH_ICE_STREAM_TRANSPORT,
+ * which has provided the integration of ICE with socket transport.
+ *
+ * The steps to use ICE session is similar for both offerer and
+ * answerer:
+ * - create ICE session with #pj_ice_sess_create(). Among other things,
+ *   application needs to specify:
+ *	- STUN configuration (pj_stun_config), containing STUN settings
+ *	  such as timeout values and the instances of timer heap and
+ *	  ioqueue.
+ *	- Session name, useful for identifying this session in the log.
+ *	- Initial ICE role (#pj_ice_sess_role). The role can be changed
+ *	  at later time with #pj_ice_sess_change_role(), and ICE session
+ *	  can also change its role automatically when it detects role
+ *	  conflict.
+ *	- Number of components in the media session.
+ *	- Callback to receive ICE events (#pj_ice_sess_cb)
+ *	- Optional local ICE username and password. If these arguments
+ *	  are NULL, they will be generated randomly.
+ * - Add local candidates for each component, with #pj_ice_sess_add_cand().
+ *   A candidate is represented with #pj_ice_sess_cand structure.
+ *   Each component must be provided with at least one candidate, and
+ *   all components must have the same number of candidates. Failing
+ *   to comply with this will cause failure during pairing process.
+ * - Create offer to describe local ICE candidates. ICE session does not
+ *   provide a function to create such offer, but application should be
+ *   able to create one since it knows about all components and candidates.
+ *   If application uses \ref PJNATH_ICE_STREAM_TRANSPORT, it can
+ *   enumerate local candidates by calling #pj_ice_strans_enum_cands().
+ *   Application may use #pj_ice_sess_find_default_cand() to let ICE
+ *   session chooses the default transport address to be used in SDP
+ *   c= and m= lines.
+ * - Send the offer to remote endpoint using signaling such as SIP.
+ * - Once application has received the answer, it should parse this
+ *   answer, build array of remote candidates, and create check lists by
+ *   calling #pj_ice_sess_create_check_list(). This process is known as
+ *   pairing the candidates, and will result in the creation of check lists.
+ * - Once checklist has been created, application then can call
+ *   #pj_ice_sess_start_check() to instruct ICE session to start
+ *   performing connectivity checks. The ICE session performs the
+ *   connectivity checks by processing each check in the checklists.
+ * - Application will be notified about the result of ICE connectivity
+ *   checks via the callback that was given in #pj_ice_sess_create()
+ *   above.
+ *
+ * To send data, application calls #pj_ice_sess_send_data(). If ICE
+ * negotiation has not completed, ICE session would simply drop the data,
+ * and return error to caller. If ICE negotiation has completed
+ * successfully, ICE session will in turn call the \a on_tx_pkt
+ * callback of #pj_ice_sess_cb instance that was previously registered
+ * in #pj_ice_sess_create() above.
+ *
+ * When application receives any packets on the underlying sockets, it
+ * must call #pj_ice_sess_on_rx_pkt(). The ICE session will inspect the
+ * packet to decide whether to process it locally (if the packet is a
+ * STUN message and is part of ICE session) or otherwise pass it back to
+ * application via \a on_rx_data callback.
  */
 
Index: pjproject/trunk/pjnath/include/pjnath/ice_strans.h
===================================================================
--- pjproject/trunk/pjnath/include/pjnath/ice_strans.h	(revision 1486)
+++ pjproject/trunk/pjnath/include/pjnath/ice_strans.h	(revision 1487)
@@ -36,5 +36,5 @@
 /**
  * @defgroup PJNATH_ICE_STREAM_TRANSPORT ICE Stream Transport
- * @brief Transport for media stream using ICE
+ * @brief Transport for media streams using ICE
  * @ingroup PJNATH_ICE
  * @{
@@ -45,5 +45,5 @@
  *
  * ICE stream transport, as represented by #pj_ice_strans structure, is an ICE
- * capable component for transporting media within a media stream. 
+ * capable component for transporting media streams within a media session. 
  * It consists of one or more transport sockets (typically two for RTP
  * based communication - one for RTP and one for RTCP), and an 
@@ -68,21 +68,46 @@
  * transport is capable for restarting the ICE session being used and to
  * send STUN keep-alives for its STUN server reflexive and relayed
- * candidates.
- *
- * \subsection PJNATH_ICE_ST_TRA_INIT Stream Transport Initialization
+ * candidates. When ICE stream transport detects that the STUN mapped
+ * address has changed in the keep-alive response, it will automatically
+ * update its address to the new address, and notify the application via
+ * \a on_addr_change() function of the #pj_ice_strans_cb callback.
+ *
+ * \subsection PJNATH_ICE_ST_TRA_INIT Initialization
  *
  * Application creates the ICE stream transport by calling 
- * #pj_ice_strans_create() function.
+ * #pj_ice_strans_create() function. Among other things, application needs
+ * to specify:
+ *	- STUN configuration (pj_stun_config), containing STUN settings
+ *	  such as timeout values and the instances of timer heap and
+ *	  ioqueue.
+ *	- Session name, useful for identifying this session in the log.
+ *	- Number of ICE components.
+ *	- Arbitrary user data, useful when associating the ICE session
+ *	  with some application's data structure.
+ *	- A callback (#pj_ice_strans_cb) to receive events from the ICE
+ *	  stream transport. Two of the most important fields in this
+ *	  callback structure are \a on_rx_data() to notify application
+ *	  about incoming data (perhaps RTP or RTCP packet), and
+ *	  \a on_ice_complete() to notify application that ICE negotiation
+ *	  has completed, either successfully or with failure.
  *
  * After the ICE stream transport is created, application may set up the
  * STUN servers to be used to obtain STUN server reflexive and relayed
  * candidate, by calling #pj_ice_strans_set_stun_domain() or 
- * #pj_ice_strans_set_stun_srv(). Then it has to create each component by
- * calling #pj_ice_strans_create_comp(); this would create an actual socket
+ * #pj_ice_strans_set_stun_srv().
+ *
+ * Application then creates each component by calling 
+ * #pj_ice_strans_create_comp(); this would create an actual socket
  * which listens to the specified local address, and it would also
  * perform lookup to find various transport address candidates for this
  * socket.
+ *
+ * Adding component may involve contacting STUN and TURN servers to get
+ * STUN mapped address and allocate TURN relay channel, and this process
+ * may take some time to complete. Once application has added all
+ * components, it can check whether server reflexive and relayed 
+ * candidates have been acquired, by calling #pj_ice_strans_get_comps_status().
  * 
- * \subsection PJNATH_ICE_ST_TRA_INIT_ICE ICE Session Initialization
+ * \subsection PJNATH_ICE_ST_TRA_INIT_ICE Starting ICE Session
  *
  * When application is about to send an offer containing ICE capability,
@@ -96,10 +121,28 @@
  * \subsection PJNATH_ICE_ST_TRA_START Starting Connectivity Checks
  *
- * Once application receives the SDP from remote, it can start ICE
- * connectivity checks by calling #pj_ice_strans_start_ice(), specifying
- * the username, password, and candidates of the remote agent. The ICE
- * session/transport will then notify the application via the callback
- * when ICE connectivity checks completes, either successfully or with
- * failure.
+ * Once application receives the SDP from remote, it pairs local candidates
+ * with remote candidates, and can start ICE connectivity checks. This is
+ * done by calling #pj_ice_strans_start_ice(), specifying
+ * the remote candidate list, and remote username and password. If the
+ * pairing process is successful, ICE connectivity checks will begin
+ * immediately. The ICE session/transport will then notify the application 
+ * via the callback when ICE connectivity checks completes, either 
+ * successfully or with failure.
+ *
+ * \subsection PJNATH_ICE_ST_TRA_SEND_RECV Sending and Receiving Data
+ *
+ * Application can send data (normally RTP or RTCP packets) at any time
+ * by calling #pj_ice_strans_sendto(). This function takes a destination
+ * address as one of the arguments, and this destination address should
+ * be taken from the default transport address of the component (that is
+ * the address in SDP c= and m= lines, or in a=rtcp attribute). 
+ * If ICE negotiation is in progress, this function will send the data 
+ * to the destination address. Otherwise if ICE negotiation has completed
+ * successfully, this function will send the data to the nominated remote 
+ * address, as negotiated by ICE.
+ *
+ * Upon receiving incoming data (that is a non-STUN  message), the ICE
+ * stream transport will notify the application by calling \a on_rx_data()
+ * of the #pj_ice_strans_cb callback.
  *
  * \subsection PJNATH_ICE_ST_TRA_STOP Stopping ICE Session
@@ -109,5 +152,9 @@
  * ICE session within this ICE stream transport. Note that this WILL NOT
  * destroy the sockets/transports, it only destroys the ICE session
- * within this ICE stream transport.
+ * within this ICE stream transport. It is recommended that application 
+ * retains the ICE stream transport to speed up the process of setting up
+ * the next call. The ICE stream transport will continue to send STUN 
+ * keep-alive packets to keep the NAT binding open and to detect change 
+ * in STUN mapped address.
  *
  * \subsection PJNATH_ICE_ST_TRA_RESTART Restarting ICE Session
@@ -570,6 +617,6 @@
  * Send outgoing packet using this transport. If ICE checks have not 
  * produced a valid check for the specified component ID, this function 
- * will return with failure. Otherwise it will send the packet to remote
- * destination using the nominated local candidate as have been checked
+ * send to the destination address. Otherwise it will send the packet to
+ * remote destination using the nominated local candidate as have been checked
  * previously.
  *
Index: pjproject/trunk/pjnath/include/pjnath/types.h
===================================================================
--- pjproject/trunk/pjnath/include/pjnath/types.h	(revision 1486)
+++ pjproject/trunk/pjnath/include/pjnath/types.h	(revision 1487)
@@ -118,24 +118,37 @@
  * The STUN library is organized as follows:
  *
- *  - the lowest layer of the library is \ref PJNATH_STUN_MSG. This layer
- *    provides STUN message representation, validation, parsing, and
- *    debugging (dump to log) of STUN messages.
- *
- *  - for client, the next higher layer is \ref PJNATH_STUN_TRANSACTION,
- *    which manages retransmissions of STUN request.
+ *  - for both client and server, the highest abstraction is
+ *    \ref PJNATH_STUN_SESSION, which provides management of incoming
+ *    and outgoing messages and association of STUN credential to
+ *    a STUN session. 
+ *
+ *  - for client, the next layer below is \ref PJNATH_STUN_TRANSACTION,
+ *    which manages retransmissions of STUN request. Server side STUN
+ *    transaction is handled in \ref PJNATH_STUN_SESSION layer above.
  *
  *  - \ref PJNATH_STUN_AUTH provides mechanism to verify STUN
  *    credential in incoming STUN messages.
  *
- *  - for both client and server, the next higher abstraction is
- *    \ref PJNATH_STUN_SESSION, which provides management of incoming
- *    and outgoing messages and association of STUN credential to
- *    a STUN session.
- *
- * As mentioned previously, all STUN library components are independent
- * of any transports. Application gives incoming packet
- * to the STUN components for processing. and it must supply the STUN 
- * components with callback to send outgoing messages.
- * 
+ *  - the lowest layer of the library is \ref PJNATH_STUN_MSG. This layer
+ *    provides STUN message representation, validation, parsing, 
+ *    encoding MESSAGE-INTEGRITY for outgoing messages, and
+ *    debugging (dump to log) of STUN messages.
+ *
+ * All STUN library components are independent of any transports. 
+ * Application gives incoming packet to the STUN components for processing,
+ * and it must supply the STUN components with callback to send outgoing 
+ * messages.
+ * 
+ *
+ * \subsection PJNATH_STUN_USING Using STUN Library
+ *
+ * [The developers guide documentation can certainly be improved here]
+ *
+ * For a sample STUN and TURN client, please see <tt>pjstun-client</tt>
+ * project under <tt>pjnath/src</tt> directory.
+ *
+ * For a sample STUN and TURN server, please see <tt>pjstun-srv-test</tt>
+ * project under <tt>pjnath/src</tt> directory.
+ *
  *
  * \subsection PJNATH_STUN_REF STUN Reference
@@ -171,4 +184,17 @@
  * The ICE library is organized as follows:
  *
+ *  - the highest abstraction is ICE media transport, which maintains
+ *    ICE stream transport and provides SDP translations to be used
+ *    for SIP offer/answer exchanges. ICE media transport is part
+ *    of PJMEDIA library.
+ *
+ *  - higher in the hierarchy is \ref PJNATH_ICE_STREAM_TRANSPORT,
+ *    which binds ICE with UDP sockets, and provides STUN binding
+ *    and relay/TURN allocation for the sockets. This component can
+ *    be directly used by application, although normally application
+ *    should use the next higher abstraction since it provides
+ *    SDP translations and better integration with other PJ libraries
+ *    such as PJSIP and PJMEDIA.
+ *
  *  - the lowest layer is \ref PJNATH_ICE_SESSION, which provides 
  *    ICE management and negotiation in a transport-independent way.
@@ -178,15 +204,11 @@
  *    ICE implementors.
  *
- *  - higher in the hierarchy is \ref PJNATH_ICE_STREAM_TRANSPORT,
- *    which binds ICE with UDP sockets, and provides STUN binding
- *    and relay/TURN allocation for the sockets. This component can
- *    be directly used by application, although normally application
- *    should use the next higher abstraction below since it provides
- *    SDP translations and better integration with other PJ libraries
- *    such as PJSIP and PJMEDIA.
- *
- *  - the highest abstraction is ICE media transport, which maintains
- *    ICE stream transport and provides SDP translations to be used
- *    for SIP offer/answer exchanges.
+ * \subsection PJNATH_ICE_USING Using the ICE Library
+ *
+ * For ICE implementation that has been integrated with socket transport,
+ * please see \ref PJNATH_ICE_STREAM_TRANSPORT_USING.
+ *
+ * For ICE implementation that has not been integrated with socket
+ * transport, please see \ref pj_ice_sess_using_sec.
  *
  * \subsection PJNATH_ICE_REF Reference
