Index: /pjproject/trunk/pjsip-apps/src/py_pjsua/py_pjsua.c
===================================================================
--- /pjproject/trunk/pjsip-apps/src/py_pjsua/py_pjsua.c	(revision 917)
+++ /pjproject/trunk/pjsip-apps/src/py_pjsua/py_pjsua.c	(revision 918)
@@ -7182,9 +7182,9 @@
         translate_hdr(pool, &msg_data.hdr_list, omd->hdr_list);
         status = pjsua_call_make_call(acc_id, &dst_uri, 
-			options, &user_data, &msg_data, &call_id);	
+			options, (void*)user_data, &msg_data, &call_id);	
         pj_pool_release(pool);
     } else {
         status = pjsua_call_make_call(acc_id, &dst_uri, 
-			options, &user_data, NULL, &call_id);	
+			options, (void*)user_data, NULL, &call_id);	
     }
 
@@ -7339,5 +7339,5 @@
     }	
     
-    status = pjsua_call_set_user_data(call_id, &user_data);
+    status = pjsua_call_set_user_data(call_id, (void*)user_data);
     
     
@@ -7352,5 +7352,5 @@
 {    	
     int call_id;
-    int * user_data;	
+    void * user_data;	
     
 
@@ -7363,5 +7363,5 @@
     
     
-    return Py_BuildValue("i", *user_data);
+    return Py_BuildValue("i", (int)user_data);
 }
 
Index: /pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h
===================================================================
--- /pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h	(revision 917)
+++ /pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h	(revision 918)
@@ -48,11 +48,17 @@
 
 
-/**
- * @defgroup PJSUA_LIB PJSUA API
+PJ_BEGIN_DECL
+
+
+/**
+ * @defgroup PJSUA_LIB PJSUA API - High Level Softphone API for C/C++ and Python
  * @ingroup PJSIP
  * @brief Very high level API for constructing SIP UA applications.
  * @{
  *
- * PJSUA API is very high level API for constructing SIP user agent
+ * @section pjsua_api_intro A SIP User Agent API for C/C++ and Python
+ *
+ * PJSUA API is very high level API, available for C/C++ and Python language,
+ * for constructing SIP multimedia user agent
  * applications. It wraps together the signaling and media functionalities
  * into an easy to use call API, provides account management, buddy
@@ -61,4 +67,5 @@
  * voice recording, and so on.
  *
+ * @subsection pjsua_for_c_cpp C/C++ Binding
  * Application must link with <b>pjsua-lib</b> to use this API. In addition,
  * this library depends on the following libraries:
@@ -71,16 +78,47 @@
  *  - <b>pjlib</b>, 
  *
- * so application must also link with these libraries as well.
- *
+ * so application must also link with these libraries as well. For more 
+ * information, please refer to 
+ * <A HREF="http://www.pjsip.org/using.htm">Getting Started with PJSIP</A>
+ * page.
+ *
+ * @subsection pjsua_for_python Python Binding
+ *
+ * The Python binding for PJSUA-API is implemented by <b>py_pjsua</b>
+ * module, in <tt>pjsip-apps/py_pjsua</tt> directory. This module is
+ * built by building <tt>py_pjsua</tt> project in <tt>pjsip_apps</tt>
+ * Visual Studio workspace, or by invoking the usual <tt>setup.py</tt>
+ * Python installer script.
+ *
+ * The Python script then can import the PJSUA-API Python module by
+ * using <b>import py_pjsua</b> construct as usual.
+ *
+ *
+ * @section pjsua_samples
+ *
+ * Few samples are provided both in C and Python.
+ *
+  - @ref page_pjsip_sample_simple_pjsuaua_c\n
+    Very simple SIP User Agent with registration, call, and media, using
+    PJSUA-API, all in under 200 lines of code.
+
+  - @ref page_pjsip_samples_pjsua\n
+    This is the reference implementation for PJSIP and PJMEDIA.
+    PJSUA is a console based application, designed to be simple enough
+    to be readble, but powerful enough to demonstrate all features
+    available in PJSIP and PJMEDIA.\n
+
+  - Python sample\n
+    For a real simple Python sample application, have a look at
+    <A HREF="http://www.pjsip.org/trac/browser/pjproject/trunk/pjsip-apps/src/py_pjsua/pjsua_app.py">
+    <tt>pjsip-apps/src/py_pjsua/pjsua_app.py</tt></A> file.
+
  * @section root_using_pjsua_lib Using PJSUA API
  *
- * Please refer to @ref using_pjsua_lib on how to use PJSUA API.
+ * Please refer to @ref PJSUA_LIB_BASE on how to create and initialize the API.
+ * And then see the Modules on the bottom of this page for more information
+ * about specific subject.
  */ 
 
-PJ_BEGIN_DECL
-
-
-/** Forward declaration */
-typedef struct pjsua_media_config pjsua_media_config;
 
 
@@ -90,5 +128,5 @@
 
 /**
- * @defgroup PJSUA_LIB_BASE Base API
+ * @defgroup PJSUA_LIB_BASE PJSUA-API Basic API
  * @ingroup PJSUA_LIB
  * @brief Basic application creation/initialization, logging configuration, etc.
@@ -102,16 +140,21 @@
  * @subsection creating_pjsua_lib Creating PJSUA
  *
- * Before anything else, application must create PJSUA by calling #pjsua_create().
+ * Before anything else, application must create PJSUA by calling #pjsua_create()
+ * (or <tt>py_pjsua.create()</tt> from Python).
  * This, among other things, will initialize PJLIB, which is crucial before 
- * any PJLIB functions can be called.
+ * any PJLIB functions can be called, PJLIB-UTIL, and create a SIP endpoint.
+ *
+ * After this function is called, application can create a memory pool (with
+ * #pjsua_pool_create()) and read configurations from command line or file to
+ * build the settings to initialize PJSUA below.
  *
  * @subsection init_pjsua_lib Initializing PJSUA
  *
  * After PJSUA is created, application can initialize PJSUA by calling
- * #pjsua_init(). This function takes several configuration settings in the
- * argument, so application normally would want to set these configuration
- * before passing them to #pjsua_init().
- *
- * Sample code to initialize PJSUA:
+ * #pjsua_init(). This function takes several optional configuration settings 
+ * in the argument, if application wants to set them.
+ *
+ * @subsubsection init_pjsua_lib_c_cpp PJSUA-LIB Initialization (in C)
+ * Sample code to initialize PJSUA in C code:
  \code
 
@@ -160,4 +203,58 @@
  \endcode
  *
+ *
+ * @subsubsection init_pjsua_lib_python PJSUA-LIB Initialization (in Python)
+ * Sample code to initialize PJSUA in Python code:
+
+ \code
+
+import py_pjsua
+
+#
+# Initialize pjsua.
+#
+def app_init():
+	# Create pjsua before anything else
+	status = py_pjsua.create()
+	if status != 0:
+		err_exit("pjsua create() error", status)
+
+	# We use default logging config for this sample
+	log_cfg = py_pjsua.logging_config_default()
+
+	# Create and initialize pjsua config
+	# Note: for this Python module, thread_cnt must be 0 since Python
+	#       doesn't like to be called from alien thread (pjsua's thread
+	#       in this case)	    
+	ua_cfg = py_pjsua.config_default()
+	ua_cfg.thread_cnt = 0
+	ua_cfg.user_agent = "PJSUA/Python 0.1"
+
+	# Override callbacks. At the very least application would want to
+	# override the call callbacks in pjsua_config
+	ua_cfg.cb.on_incoming_call = ...
+	ua_cfg.cb.on_call_state = ...
+
+	# Use default media config for this cample
+	med_cfg = py_pjsua.media_config_default()
+
+	#
+	# Initialize pjsua!!
+	#
+	status = py_pjsua.init(ua_cfg, log_cfg, med_cfg)
+	if status != 0:
+		err_exit("pjsua init() error", status)
+
+
+
+# Utility: display PJ error and exit
+#
+def err_exit(title, rc):
+	py_pjsua.perror(THIS_FILE, title, rc)
+	exit(1)
+
+ \endcode
+
+
  * @subsection other_init_pjsua_lib Other Initialization
  *
@@ -165,8 +262,11 @@
  * need/want to perform the following tasks:
  *
- *  - create SIP transport with #pjsua_transport_create(). Please see
+ *  - create SIP transport with #pjsua_transport_create(). Application would
+ *    to call #pjsua_transport_create() for each transport types that it
+ *    wants to support (for example, UDP, TCP, and TLS). Please see
  *    @ref PJSUA_LIB_TRANSPORT section for more info.
  *  - create one or more SIP accounts with #pjsua_acc_add() or
- *    #pjsua_acc_add_local(). Please see @ref PJSUA_LIB_ACC for more info.
+ *    #pjsua_acc_add_local(). The SIP account is used for registering with
+ *    the SIP server, if any. Please see @ref PJSUA_LIB_ACC for more info.
  *  - add one or more buddies with #pjsua_buddy_add(). Please see
  *    @ref PJSUA_LIB_BUDDY section for more info.
@@ -179,6 +279,6 @@
  * After all initializations have been done, application must call
  * #pjsua_start() to start PJSUA. This function will check that all settings
- * are properly configured, and apply default settings when it's not, or
- * report error status when it is unable to recover from missing setting.
+ * have been properly configured, and apply default settings when they haven't,
+ * or report error status when it is unable to recover from missing settings.
  *
  * Most settings can be changed during run-time. For example, application
@@ -186,4 +286,5 @@
  * during run-time.
  *
+ * @subsubsection starting_pjsua_lib_c C Example for Starting PJSUA
  * Sample code:
  \code
@@ -210,4 +311,62 @@
  }
  \endcode
+
+ * @subsubsection starting_pjsua_lib_python Python Example for starting PJSUA
+ * For Python, starting PJSUA-LIB takes one more step, that is to initialize
+ * Python worker thread to poll PJSUA-LIB. This step is necessary because
+ * Python doesn't like it when it is called by an "alien" thread (that is,
+ * thread that is not created using Python API).
+ *
+ * Because of this, we cannot use a worker thread in PJSUA-LIB, because then
+ * the Python callback will be called by an "alien" thread and this would
+ * crash Python (or raise assert() probably).
+ *
+ * So because worker thread is disabled, we need to create a worker thread
+ * in Python. Note that this may not be necessary if we're creating a
+ * GUI application, because then we can attach, for example, a GUI timer
+ * object to poll the PJSUA-LIB. But because we're creating a console 
+ * application which will block at <tt>sys.stdin.readline()</tt>, we need
+ * to have a worker thread to poll PJSUA-LIB.
+
+ \code
+
+import thread
+
+C_QUIT = 0
+
+
+def app_start():
+	# Done with initialization, start pjsua!!
+	#
+	status = py_pjsua.start()
+	if status != 0:
+		py_pjsua.destroy()
+		err_exit("Error starting pjsua!", status)
+
+	# Start worker thread
+	thr = thread.start_new(worker_thread_main, (0,))
+    
+	print "PJSUA Started!!"
+
+#
+# Worker thread function.
+# Python doesn't like it when it's called from an alien thread
+# (pjsua's worker thread, in this case), so for Python we must
+# disable worker thread in pjsua and poll pjsua from Python instead.
+#
+def worker_thread_main(arg):
+	global C_QUIT
+	thread_desc = 0
+	status = py_pjsua.thread_register("python worker", thread_desc)
+	if status != 0:
+		py_pjsua.perror(THIS_FILE, "Error registering thread", status)
+	else:
+		while C_QUIT == 0:
+			py_pjsua.handle_events(50)
+		print "Worker thread quitting.."
+		C_QUIT = 2
+
+
+ \endcode
  */
 
@@ -248,4 +407,12 @@
  * #pjsua_init(). Application must call #pjsua_logging_config_default() to
  * initialize this structure with the default values.
+ *
+ * \par Sample Python Syntax:
+ * \code
+    # Python type: py_pjsua.Logging_Config
+ 
+    log_cfg = py_pjsua.logging_config_default()
+    log_cfg.level = 4
+ * \endcode
  */
 typedef struct pjsua_logging_config
@@ -280,4 +447,14 @@
      * application specific device. This function will be called for
      * log messages on input verbosity level.
+     *
+     * \par Sample Python Syntax:
+     * \code
+     # level:	integer
+     # data:	string
+     # len:	integer
+
+     def cb(level, data, len):
+	    print data,
+     * \endcode
      */
     void       (*cb)(int level, const char *data, pj_size_t len);
@@ -291,4 +468,10 @@
  *
  * @param cfg	The logging config to be initialized.
+ *
+ * \par Python Syntax:
+ * The Python function instantiates and initialize the logging config:
+ * \code
+ logging_cfg = py_pjsua.logging_config_default()
+ * \endcode
  */
 PJ_INLINE(void) pjsua_logging_config_default(pjsua_logging_config *cfg)
@@ -309,4 +492,8 @@
  * @param dst	    Destination config.
  * @param src	    Source config.
+ *
+ * \par Python Syntax:
+ * Not available (for now). Ideally we should be able to just assign
+ * one config to another, but this has not been tested.
  */
 PJ_INLINE(void) pjsua_logging_config_dup(pj_pool_t *pool,
@@ -325,4 +512,7 @@
  * although definitely application would want to implement some of
  * the important callbacks (such as \a on_incoming_call).
+ *
+ * \par Python Syntax:
+ * This callback structure is embedded on pjsua_config structure.
  */
 typedef struct pjsua_callback
@@ -331,8 +521,17 @@
      * Notify application when invite state has changed.
      * Application may then query the call info to get the
-     * detail call states.
+     * detail call states by calling  pjsua_call_get_info() function.
      *
      * @param call_id	The call index.
      * @param e		Event which causes the call state to change.
+     *
+     * \par Python Syntax:
+     * \code
+     # call_id: integer
+     # e:	an opaque object
+
+     def on_call_state(call_id, e):
+	    return
+     * \endcode
      */
     void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e);
@@ -345,4 +544,14 @@
      *			the call.
      * @param rdata	The incoming INVITE request.
+     *
+     * \par Python Syntax:
+     * \code
+     # acc_id:	integer
+     # call_id: integer
+     # rdata:	an opaque object
+
+     def on_incoming_call(acc_id, call_id, rdata):
+	    return
+     * \endcode
      */
     void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id,
@@ -355,4 +564,12 @@
      *
      * @param call_id	The call index.
+     *
+     * \par Python Syntax:
+     * \code
+     # call_id: integer
+
+     def on_call_media_state(call_id):
+	    return
+     * \endcode
      */
     void (*on_call_media_state)(pjsua_call_id call_id);
@@ -363,4 +580,13 @@
      * @param call_id	The call index.
      * @param digit	DTMF ASCII digit.
+     *
+     * \par Python Syntax:
+     * \code
+     # call_id: integer
+     # digit:	integer
+
+     def on_dtmf_digit(call_id, digit):
+	    return
+     * \endcode
      */
     void (*on_dtmf_digit)(pjsua_call_id call_id, int digit);
@@ -378,4 +604,15 @@
      * @param code	Status code to be returned for the call transfer
      *			request. On input, it contains status code 200.
+     *
+     * \par Python Syntax:
+     * \code
+     # call_id: integer
+     # dst:	string
+     # code:	integer
+
+     def on_call_transfer_request(call_id, dst, code):
+	    return code
+
+     * \endcode 
      */
     void (*on_call_transfer_request)(pjsua_call_id call_id,
@@ -390,8 +627,8 @@
      *
      * @param call_id	    Call ID.
-     * @param status_code   Status progress of the transfer request.
-     * @param status_text   Status progress text.
+     * @param st_code	    Status progress of the transfer request.
+     * @param st_text	    Status progress text.
      * @param final	    If non-zero, no further notification will
-     *			    be reported. The status_code specified in
+     *			    be reported. The st_code specified in
      *			    this callback is the final status.
      * @param p_cont	    Initially will be set to non-zero, application
@@ -399,8 +636,22 @@
      *			    to receie further notification (for example,
      *			    after it hangs up the call).
+     *
+     * \par Python Syntax:
+     * \code
+     # call_id: integer
+     # st_code: integer
+     # st_text: string
+     # final:	integer
+     # cont:	integer
+
+     # return:	cont
+
+     def on_call_transfer_status(call_id, st_code, st_text, final, cont):
+	    return cont
+     * \endcode
      */
     void (*on_call_transfer_status)(pjsua_call_id call_id,
-				    int status_code,
-				    const pj_str_t *status_text,
+				    int st_code,
+				    const pj_str_t *st_text,
 				    pj_bool_t final,
 				    pj_bool_t *p_cont);
@@ -415,4 +666,17 @@
      *			    should only return a final status (200-699).
      * @param st_text	    Optional status text to be set by application.
+     *
+     * \par Python Syntax:
+     * \code
+     # call_id: integer
+     # rdata:	an opaque object
+     # st_code: integer
+     # st_text: string
+
+     # return:	(st_code, st_text) tuple
+
+     def on_call_replace_request(call_id, rdata, st_code, st_text):
+	    return st_code, st_text
+     * \endcode
      */
     void (*on_call_replace_request)(pjsua_call_id call_id,
@@ -433,4 +697,13 @@
      * @param new_call_id   The new call.
      * @param rdata	    The incoming INVITE with Replaces request.
+     *
+     * \par Python Syntax:
+     * \code
+     # old_call_id: integer
+     # new_call_id: integer
+
+     def on_call_replaced(old_call_id, new_call_id):
+	    return
+     * \endcode
      */
     void (*on_call_replaced)(pjsua_call_id old_call_id,
@@ -444,4 +717,12 @@
      *
      * @param acc_id	    Account ID.
+     *
+     * \par Python Syntax:
+     * \code
+     # acc_id:	account ID (integer)
+
+     def on_reg_state(acc_id):
+	    return
+     * \endcode
      */
     void (*on_reg_state)(pjsua_acc_id acc_id);
@@ -452,4 +733,12 @@
      *
      * @param buddy_id	    The buddy id.
+     *
+     * \par Python Syntax:
+     * \code
+     # buddy_id:    integer
+
+     def on_buddy_state(buddy_id):
+	    return
+     * \endcode
      */
     void (*on_buddy_state)(pjsua_buddy_id buddy_id);
@@ -468,4 +757,17 @@
      * @param mime_type	    MIME type of the message.
      * @param body	    The message content.
+     *
+     * \par Python Syntax:
+     * \code
+     # call_id:	    integer
+     # from:	    string
+     # to:	    string
+     # contact:	    string
+     # mime_type:   string
+     # body:	    string
+
+     def on_pager(call_id, from, to, contact, mime_type, body):
+	    return
+     * \endcode
      */
     void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from,
@@ -486,4 +788,17 @@
      * @param status	    Delivery status.
      * @param reason	    Delivery status reason.
+     *
+     * \par Python Syntax
+     * \code
+     # call_id:	    integer
+     # to:	    string
+     # body:	    string
+     # user_data:   string
+     # status:	    integer
+     # reason:	    string
+
+     def on_pager_status(call_id, to, body, user_data, status, reason):
+	    return
+     * \endcode
      */
     void (*on_pager_status)(pjsua_call_id call_id,
@@ -505,4 +820,16 @@
      * @param is_typing	    Non-zero if peer is typing, or zero if peer
      *			    has stopped typing a message.
+     *
+     * \par Python Syntax
+     * \code
+     # call_id:	    string
+     # from:	    string
+     # to:	    string
+     # contact:	    string
+     # is_typing:   integer
+
+     def on_typing(call_id, from, to, contact, is_typing):
+	    return
+     * \endcode
      */
     void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from,
@@ -520,4 +847,11 @@
  * Before setting the values, application must call #pjsua_config_default()
  * to initialize this structure with the default values.
+ *
+ * \par Python Sample Syntax:
+ * The pjsua_config type in Python is <tt>py_pjsua.Config</tt>. Application
+ * creates the instance by calling <tt>py_pjsua.config_default()</tt>:
+ * \code
+    cfg = py_pjsua.config_default()
+ * \endcode
  */
 typedef struct pjsua_config
@@ -602,4 +936,12 @@
  *
  * @param cfg	pjsua config to be initialized.
+ *
+ * \par Python Sample Syntax:
+ * The corresponding Python function creates an instance of the config and
+ * initializes it to the default settings:
+ * \code
+    cfg = py_pjsua.config_default()
+ * \endcode
+
  */
 PJ_INLINE(void) pjsua_config_default(pjsua_config *cfg)
@@ -614,4 +956,12 @@
 /**
  * Duplicate credential.
+ *
+ * @param pool	    The memory pool.
+ * @param dst	    Destination credential.
+ * @param src	    Source credential.
+ *
+ * \par Python:
+ * Not applicable (for now). Probably we could just assign one credential
+ * variable to another, but this has not been tested.
  */
 PJ_INLINE(void) pjsip_cred_dup( pj_pool_t *pool,
@@ -629,4 +979,8 @@
 /**
  * Duplicate pjsua_config.
+ *
+ * @param pool	    The pool to get memory from.
+ * @param dst	    Destination config.
+ * @param src	    Source config.
  */
 PJ_INLINE(void) pjsua_config_dup(pj_pool_t *pool,
@@ -660,4 +1014,11 @@
  * Application MUST call #pjsua_msg_data_init() to initialize this
  * structure before setting its values.
+ *
+ * \par Python Syntax
+ * The data type in Python is <tt>py_pjsua.Msg_Data</tt>. Application is
+ * recommended to instantiate the structure by using this construct:
+ * \code
+    msg_data = py_pjsua.msg_data_init()
+ * \endcode
  */
 typedef struct pjsua_msg_data
@@ -665,4 +1026,12 @@
     /**
      * Additional message headers as linked list.
+     *
+     * \par Python:
+     * This field is implemented as string linked-list in Python, where each
+     * string describes the header. For example:
+     \code
+	msg_data = py_pjsua.Msg_Data()
+	msg_data.hdr_list = ["Subject: Hello py_pjsua!", "Priority: very low"]
+     \endcode
      */
     pjsip_hdr	hdr_list;
@@ -685,4 +1054,10 @@
  *
  * @param msg_data  Message data to be initialized.
+ *
+ * \par Python
+ * The corresponding Python function creates and initializes the structure:
+ * \code
+    msg_data = py_pjsua.msg_data_init()
+ * \endcode
  */
 PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data)
@@ -701,6 +1076,15 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.create()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_create(void);
+
+
+/* Forward declaration */
+typedef struct pjsua_media_config pjsua_media_config;
 
 
@@ -717,4 +1101,13 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function is similar in Python:
+ * \code
+    status = py_pjsua.init(ua_cfg, log_cfg, media_cfg)
+ * \endcode
+ * Note that \a ua_cfg, \a log_cfg, and \a media_cfg are optional, and
+ * the Python script may pass None if it doesn't want to configure the 
+ * setting.
  */
 PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg,
@@ -731,4 +1124,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function is similar in Python:
+ * \code
+    status = py_pjsua.start()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_start(void);
@@ -747,4 +1146,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function is similar in Python:
+ * \code
+    status = py_pjsua.destroy()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_destroy(void);
@@ -763,5 +1168,11 @@
  * @return  The number of events that have been handled during the
  *	    poll. Negative value indicates error, and application
- *	    can retrieve the error as (err = -return_value).
+ *	    can retrieve the error as (status = -return_value).
+ *
+ * \par Python:
+ * The function is similar in Python:
+ * \code
+    n = py_pjsua.handle_events(msec_timeout)
+ * \endcode
  */
 PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout);
@@ -777,4 +1188,10 @@
  *
  * @return		The pool, or NULL when there's no memory.
+ *
+ * \par Python:
+ * Python script may also create a pool object from the script:
+ * \code
+    pool = py_pjsua.pool_create(name, init_size, increment)
+ * \endcode
  */
 PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size,
@@ -789,4 +1206,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function is similar in Python:
+ * \code
+    status = py_pjsua.reconfigure_logging(log_cfg)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c);
@@ -799,4 +1222,12 @@
  * 
  * @return		SIP endpoint instance.
+ *
+ * \par Python:
+ * Application may retrieve the SIP endpoint instance:
+ * \code
+    endpt = py_pjsua.get_pjsip_endpt()
+ * \endcode
+ * However currently the object is just an opaque object and does not have
+ * any use for Python scripts.
  */
 PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void);
@@ -807,4 +1238,12 @@
  *
  * @return		Media endpoint instance.
+ *
+ * \par Python:
+ * Application may retrieve the media endpoint instance:
+ * \code
+    endpt = py_pjsua.get_pjmedia_endpt()
+ * \endcode
+ * However currently the object is just an opaque object and does not have
+ * any use for Python scripts.
  */
 PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void);
@@ -815,4 +1254,12 @@
  *
  * @return		Pool factory currently used by PJSUA.
+ *
+ * \par Python:
+ * Application may retrieve the pool factory instance:
+ * \code
+    endpt = py_pjsua.get_pool_factory()
+ * \endcode
+ * However currently the object is just an opaque object and does not have
+ * any use for Python scripts.
  */
 PJ_DECL(pj_pool_factory*) pjsua_get_pool_factory(void);
@@ -829,9 +1276,14 @@
  * URL is valid, PJ_SUCCESS will be returned.
  *
- * @param c_url		The URL, as NULL terminated string.
- *
- * @return		PJ_SUCCESS on success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url);
+ * @param url		The URL, as NULL terminated string.
+ *
+ * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.verify_sip_url(url)
+ * \endcode
+ */
+PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *url);
 
 
@@ -843,4 +1295,9 @@
  * @param title		Message title for the error.
  * @param status	Status code.
+ *
+ * \par Python:
+ * \code
+    py_pjsua.perror(sender, title, status)
+ * \endcode
  */
 PJ_DECL(void) pjsua_perror(const char *sender, const char *title, 
@@ -861,14 +1318,17 @@
 
 /**
- * @defgroup PJSUA_LIB_TRANSPORT Signaling Transport
+ * @defgroup PJSUA_LIB_TRANSPORT PJSUA-API Signaling Transport
  * @ingroup PJSUA_LIB
  * @brief API for managing SIP transports
  * @{
- * SIP transport must be created before adding an account. SIP transport is
- * created by calling #pjsua_transport_create() function.
- */
-
-
-/** SIP transport identification */
+ *
+ * PJSUA-API supports creating multiple transport instances, for example UDP,
+ * TCP, and TLS transport. SIP transport must be created before adding an 
+ * account.
+ */
+
+
+/** SIP transport identification.
+ */
 typedef int pjsua_transport_id;
 
@@ -910,6 +1370,15 @@
 /**
  * Call this function to initialize STUN config with default values.
+ * STUN config is normally embedded inside pjsua_transport_config, so
+ * normally there is no need to call this function and rather just
+ * call pjsua_transport_config_default() instead.
  *
  * @param cfg	    The STUN config to be initialized.
+ *
+ * \par Python:
+ * The corresponding Python function creates and initialize the config:
+ * \code
+    stun_cfg = py_pjsua.stun_config_default()
+ * \endcode
  */
 PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg)
@@ -924,4 +1393,11 @@
  * MUST call #pjsua_transport_config_default() to initialize its
  * values with default settings.
+ *
+ * \par Python:
+ * The data type in Python is <tt>py_pjsua.Transport_Config</tt>,
+ * although application can just do this to create the instance:
+ * \code
+    transport_cfg = py_pjsua.transport_config_default()
+ * \endcode
  */
 typedef struct pjsua_transport_config
@@ -983,4 +1459,10 @@
  *
  * @param cfg	    The UDP config to be initialized.
+ *
+ * \par Python:
+ * The corresponding Python function is rather different:
+ * \code
+    transport_cfg = py_pjsua.transport_config_default()
+ * \endcode
  */
 PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg)
@@ -997,4 +1479,9 @@
  *
  * @param cfg	    The STUN config to be initialized.
+ *
+ * \par Python:
+ * \code
+    py_pjsua.normalize_stun_config(cfg)
+ * \code
  */
 PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg )
@@ -1023,4 +1510,12 @@
 /**
  * Duplicate transport config.
+ *
+ * @param pool		The pool.
+ * @param dst		The destination config.
+ * @param src		The source config.
+ *
+ * \par Python:
+ * Not applicable. One should be able to just copy one variable instance
+ * to another in Python.
  */
 PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool,
@@ -1048,4 +1543,7 @@
  * This structure describes transport information returned by
  * #pjsua_transport_get_info() function.
+ *
+ * \par Python:
+ * The corresponding data type in Python is <tt>py_pjsua.Transport_Info</tt>.
  */
 typedef struct pjsua_transport_info
@@ -1109,4 +1607,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The corresponding Python function returns (status,id) tuple:
+ * \code
+    status, transport_id = py_pjsua.transport_create(type, cfg)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type,
@@ -1115,5 +1619,7 @@
 
 /**
- * Register transport that has been created by application.
+ * Register transport that has been created by application. This function
+ * is useful if application wants to implement custom SIP transport and use
+ * it with pjsua.
  *
  * @param tp		Transport instance.
@@ -1121,4 +1627,8 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * Not applicable (for now), because one cannot create a custom transport
+ * from Python script.
  */
 PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp,
@@ -1127,5 +1637,8 @@
 
 /**
- * Enumerate all transports currently created in the system.
+ * Enumerate all transports currently created in the system. This function
+ * will return all transport IDs, and application may then call 
+ * #pjsua_transport_get_info() function to retrieve detailed information
+ * about the transport.
  *
  * @param id		Array to receive transport ids.
@@ -1134,4 +1647,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function returns list of integers representing transport ids:
+ * \code
+    [int] = py_pjsua.enum_transports()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[],
@@ -1146,4 +1665,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    transport_info = py_pjsua.transport_get_info(id)
+ * \endcode
+ * The Python function returns None on error.
  */
 PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id,
@@ -1161,4 +1686,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.transport_set_enable(id, enabled)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id,
@@ -1179,4 +1709,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.transport_close(id, force)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id,
@@ -1196,10 +1731,16 @@
 
 /**
- * @defgroup PJSUA_LIB_ACC Account Management
+ * @defgroup PJSUA_LIB_ACC PJSUA-API Accounts Management
  * @ingroup PJSUA_LIB
- * @brief PJSUA supports multiple accounts..
+ * @brief PJSUA Accounts management
  * @{
+ *
  * PJSUA accounts provide identity (or identities) of the user who is currently
- * using the application. More than one account maybe created with PJSUA.
+ * using the application. In SIP terms, the identity is used as the <b>From</b>
+ * header in outgoing requests.
+ *
+ * PJSUA-API supports creating and managing multiple accounts. The maximum
+ * number of accounts is limited by a compile time constant
+ * <tt>PJSUA_MAX_ACC</tt>.
  *
  * Account may or may not have client registration associated with it.
@@ -1207,11 +1748,13 @@
  * credentials</b>, which are used when sending SIP request messages using the
  * account. An account also has presence's <b>online status</b>, which
- * will be reported to remote peer when the subscribe to the account's
- * presence.
+ * will be reported to remote peer when they subscribe to the account's
+ * presence, or which is published to a presence server if presence 
+ * publication is enabled for the account.
  *
  * At least one account MUST be created in the application. If no user
  * association is required, application can create a userless account by
  * calling #pjsua_acc_add_local(). A userless account identifies local endpoint
- * instead of a particular user.
+ * instead of a particular user, and it correspond with a particular
+ * transport instance.
  *
  * Also one account must be set as the <b>default account</b>, which is used as
@@ -1262,4 +1805,12 @@
  * adding a new account with #pjsua_acc_add(). Application MUST initialize
  * this structure first by calling #pjsua_acc_config_default().
+ *
+ * \par Python:
+ * The data type in Python is <tt>py_pjsua.Acc_Config</tt>, but normally
+ * application can just use the snippet below to create and initialize
+ * the account config:
+ * \code
+    acc_cfg = py_pjsua.acc_config_default()
+ * \endcode
  */
 typedef struct pjsua_acc_config
@@ -1304,4 +1855,7 @@
     /**
      * Number of proxies in the proxy array below.
+     *
+     * \par Python:
+     * Not applicable, as \a proxy is implemented as list of strings.
      */
     unsigned	    proxy_cnt;
@@ -1319,4 +1873,7 @@
      * then these account proxies will be placed after the global outbound
      * proxies in the routeset.
+     *
+     * \par Python:
+     * This will be list of strings.
      */
     pj_str_t	    proxy[PJSUA_ACC_MAX_PROXIES];
@@ -1330,4 +1887,7 @@
     /** 
      * Number of credentials in the credential array.
+     *
+     * \par Python:
+     * Not applicable, since \a cred_info is a list of credentials.
      */
     unsigned	    cred_count;
@@ -1339,4 +1899,7 @@
      * example when the requests are expected to be challenged by the
      * proxies in the route set.
+     *
+     * \par Python:
+     * This field is a list of credentials.
      */
     pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES];
@@ -1362,4 +1925,11 @@
  *
  * @param cfg	    The account config to be initialized.
+ *
+ * \par Python:
+ * In Python, this function both creates and initializes the account
+ * config:
+ * \code
+    acc_cfg = py_pjsua.acc_config_default()
+ * \endcode
  */
 PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg)
@@ -1376,4 +1946,7 @@
  * Account info. Application can query account info by calling 
  * #pjsua_acc_get_info().
+ *
+ * \par Python:
+ * The data type in Python is <tt>py_pjsua.Acc_Info</tt>.
  */
 typedef struct pjsua_acc_info
@@ -1435,4 +2008,9 @@
  *
  * @return		Current number of accounts.
+ *
+ * \par Python:
+ * \code
+    count = py_pjsua.acc_get_count()
+ * \endcode
  */
 PJ_DECL(unsigned) pjsua_acc_get_count(void);
@@ -1445,4 +2023,9 @@
  *
  * @return		Non-zero if account ID is valid.
+ *
+ * \par Python:
+ * \code
+    is_valid = py_pjsua.acc_is_valid(acc_id)
+ * \endcode
  */
 PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id);
@@ -1456,4 +2039,9 @@
  *
  * @return		PJ_SUCCESS on success.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.acc_set_default(acc_id)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_set_default(pjsua_acc_id acc_id);
@@ -1467,4 +2055,9 @@
  * @return		The default account ID, or PJSUA_INVALID_ID if no
  *			default account is configured.
+ *
+ * \par Python:
+ * \code
+    acc_id = py_pjsua.acc_get_default()
+ * \endcode
  */
 PJ_DECL(pjsua_acc_id) pjsua_acc_get_default(void);
@@ -1480,5 +2073,5 @@
  *
  *
- * @param cfg		Account configuration.
+ * @param acc_cfg	Account configuration.
  * @param is_default	If non-zero, this account will be set as the default
  *			account. The default account will be used when sending
@@ -1490,6 +2083,12 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg,
+ *
+ * \par Python:
+ * The function returns (status, account_id) tuple:
+ * \code
+    status, account_id = py_pjsua.acc_add(acc_cfg, is_default)
+ * \endcode
+ */
+PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *acc_cfg,
 				   pj_bool_t is_default,
 				   pjsua_acc_id *p_acc_id);
@@ -1511,4 +2110,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function returns (status, account_id) tuple:
+ * \code
+    status, account_id = py_pjsua.acc_add_local(tid, is_default)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid,
@@ -1524,4 +2129,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.acc_del(acc_id)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id);
@@ -1532,10 +2142,15 @@
  *
  * @param acc_id	Id of the account to be modified.
- * @param cfg		New account configuration.
- *
- * @return		PJ_SUCCESS on success, or the appropriate error code.
+ * @param acc_cfg	New account configuration.
+ *
+ * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.acc_modify(acc_id, acc_cfg)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id,
-				      const pjsua_acc_config *cfg);
+				      const pjsua_acc_config *acc_cfg);
 
 
@@ -1549,4 +2164,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.acc_set_online_status(acc_id, is_online)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id,
@@ -1566,4 +2186,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.acc_set_registration(acc_id, renew)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, 
@@ -1578,4 +2203,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    acc_info = py_pjsua.acc_get_info(acc_id)
+ * \endcode
+ * The function returns None if account ID is not valid.
  */
 PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id,
@@ -1595,4 +2226,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function takes no argument and returns list of account Ids:
+ * \code
+  [acc_ids] = py_pjsua.enum_accs()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[],
@@ -1608,4 +2245,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function takes no argument and returns list of account infos:
+ * \code
+    [acc_info] = py_pjsua.acc_enum_info()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[],
@@ -1620,4 +2263,9 @@
  *
  * @return		Account id.
+ *
+ * \par Python:
+ * \code
+    acc_id = py_pjsua.acc_find_for_outgoing(url)
+ * \endcode
  */
 PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url);
@@ -1631,4 +2279,9 @@
  *
  * @return		Account id.
+ *
+ * \par Python:
+ * \code
+    acc_id = py_pjsua.acc_find_for_outgoing(url)
+ * \endcode
  */
 PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata);
@@ -1645,4 +2298,10 @@
  *
  * @return		PJ_SUCCESS on success, other on error.
+ *
+ * \par Python:
+ * This function is still experimental in Python:
+ * \code
+    uri = py_pjsua.acc_create_uac_contact(pool, acc_id, uri)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_create_uac_contact( pj_pool_t *pool,
@@ -1663,4 +2322,10 @@
  *
  * @return		PJ_SUCCESS on success, other on error.
+ *
+ * \par Python:
+ * This function is still experimental in Python:
+ * \code
+    uri = py_pjsua.acc_create_uas_contact(pool, acc_id, rdata)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_acc_create_uas_contact( pj_pool_t *pool,
@@ -1686,4 +2351,7 @@
  *
  * @return		PJ_SUCCESS on success.
+ *
+ * \par Python:
+ * Not yet implemented.
  */
 PJ_DECL(pj_status_t) pjsua_acc_set_transport(pjsua_acc_id acc_id,
@@ -1702,5 +2370,5 @@
 
 /**
- * @defgroup PJSUA_LIB_CALL Calls
+ * @defgroup PJSUA_LIB_CALL PJSUA-API Calls Management
  * @ingroup PJSUA_LIB
  * @brief Call manipulation.
@@ -1740,4 +2408,7 @@
 /**
  * This structure describes the information and current status of a call.
+ *
+ * \par Python:
+ * The type name is <tt>py_pjsua.Call_Info</tt>.
  */
 typedef struct pjsua_call_info
@@ -1814,4 +2485,9 @@
  *
  * @return		Maximum number of calls configured.
+ *
+ * \par Python:
+ * \code
+    count = py_pjsua.call_get_max_count()
+ * \endcode
  */
 PJ_DECL(unsigned) pjsua_call_get_max_count(void);
@@ -1821,4 +2497,9 @@
  *
  * @return		Number of currently active calls.
+ *
+ * \par Python:
+ * \code
+    count = py_pjsua.call_get_count()
+ * \endcode
  */
 PJ_DECL(unsigned) pjsua_call_get_count(void);
@@ -1833,4 +2514,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * This function takes no argument and return list of call Ids.
+ * \code
+    [call_ids] = py_pjsua.enum_calls()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_enum_calls(pjsua_call_id ids[],
@@ -1852,4 +2539,13 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The Python function returns (status, call_id) tuple:
+ * \code
+    status, call_id = py_pjsua.call_make_call(acc_id, dst_uri, options, 
+					      user_data, msg_data)
+ * \endcode
+ * Note: the \a user_data in Python function is an integer, and the 
+ * \a msg_data can be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_call_make_call(pjsua_acc_id acc_id,
@@ -1868,4 +2564,9 @@
  *
  * @return		Non-zero if call is active.
+ *
+ * \par Python:
+ * \code
+    bool = py_pjsua.call_is_active(call_id)
+ * \endcode
  */
 PJ_DECL(pj_bool_t) pjsua_call_is_active(pjsua_call_id call_id);
@@ -1878,4 +2579,9 @@
  *
  * @return		Non-zero if yes.
+ *
+ * \par Python:
+ * \code
+    bool = py_pjsua.call_has_media(call_id)
+ * \endcode
  */
 PJ_DECL(pj_bool_t) pjsua_call_has_media(pjsua_call_id call_id);
@@ -1889,4 +2595,9 @@
  * @return		Conference port ID, or PJSUA_INVALID_ID when the 
  *			media has not been established or is not active.
+ *
+ * \par Python:
+ * \code
+    slot = py_pjsua.call_get_conf_port(call_id)
+ * \endcode
  */
 PJ_DECL(pjsua_conf_port_id) pjsua_call_get_conf_port(pjsua_call_id call_id);
@@ -1899,4 +2610,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    call_info = py_pjsua.call_get_info(call_id)
+ * \endcode
+ * \a call_info return value will be set to None if call_id is not valid.
  */
 PJ_DECL(pj_status_t) pjsua_call_get_info(pjsua_call_id call_id,
@@ -1912,4 +2629,10 @@
  *
  * @return		The user data.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_set_user_data(call_id, user_data)
+ * \endcode
+ * The \a user_data is an integer in the Python function.
  */
 PJ_DECL(pj_status_t) pjsua_call_set_user_data(pjsua_call_id call_id,
@@ -1924,4 +2647,10 @@
  *
  * @return		The user data.
+ *
+ * \par Python:
+ * \code
+    user_data = py_pjsua.call_get_user_data(call_id)
+ * \endcode
+ * The \a user_data is an integer.
  */
 PJ_DECL(void*) pjsua_call_get_user_data(pjsua_call_id call_id);
@@ -1941,4 +2670,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_answer(call_id, code, reason, msg_data)
+ * \endcode
+ * Arguments \a reason and \a msg_data may be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_call_answer(pjsua_call_id call_id, 
@@ -1965,4 +2700,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_hangup(call_id, code, reason, msg_data)
+ * \endcode
+ * Arguments \a reason and \a msg_data may be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_call_hangup(pjsua_call_id call_id,
@@ -1984,4 +2725,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_set_hold(call_id, msg_data)
+ * \endcode
+ * Argument \a msg_data may be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_call_set_hold(pjsua_call_id call_id,
@@ -2002,4 +2749,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_reinvite(call_id, unhold, msg_data)
+ * \endcode
+ * Argument \a msg_data may be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_call_reinvite(pjsua_call_id call_id,
@@ -2024,4 +2777,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_xfer(call_id, dest, msg_data)
+ * \endcode
+ * Argument \a msg_data may be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_call_xfer(pjsua_call_id call_id, 
@@ -2052,4 +2811,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_xfer_replaces(call_id, dest_call_id, options, msg_data)
+ * \endcode
+ * Argument \a msg_data may be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_call_xfer_replaces(pjsua_call_id call_id, 
@@ -2062,7 +2827,12 @@
  *
  * @param call_id	Call identification.
- * @param digits	DTMF digits to be sent.
- *
- * @return		PJ_SUCCESS on success, or the appropriate error code.
+ * @param digits	DTMF string digits to be sent.
+ *
+ * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_dial_dtmf(call_id, digits)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_call_dial_dtmf(pjsua_call_id call_id, 
@@ -2083,4 +2853,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_send_im(call_id, mime_type, content, msg_data, user_data)
+ * \endcode
+ * Note that the \a user_data argument is an integer in Python.
  */
 PJ_DECL(pj_status_t) pjsua_call_send_im( pjsua_call_id call_id, 
@@ -2101,4 +2877,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.call_send_typing_ind(call_id, is_typing, msg_data)
+ * \endcode
+ * Argument \a msg_data may be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_call_send_typing_ind(pjsua_call_id call_id, 
@@ -2109,4 +2891,9 @@
  * Terminate all calls. This will initiate #pjsua_call_hangup() for all
  * currently active calls. 
+ *
+ * \par Python:
+ * \code
+    py_pjsua.call_hangup_all()
+ * \endcode
  */
 PJ_DECL(void) pjsua_call_hangup_all(void);
@@ -2123,4 +2910,10 @@
  *
  * @return		PJ_SUCCESS on success.
+ *
+ * \par Python:
+ * \code
+    string = py_pjsua.call_dump(call_id, with_media, max_len, indent)
+ * \endcode
+ * The \a max_len argument is the desired maximum length to be allocated.
  */
 PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id, 
@@ -2141,8 +2934,11 @@
 
 /**
- * @defgroup PJSUA_LIB_BUDDY Buddy, Presence, and Instant Messaging
+ * @defgroup PJSUA_LIB_BUDDY PJSUA-API Buddy, Presence, and Instant Messaging
  * @ingroup PJSUA_LIB
  * @brief Buddy management, buddy's presence, and instant messaging.
  * @{
+ *
+ * This section describes PJSUA-APIs related to buddies management,
+ * presence management, and instant messaging.
  */
 
@@ -2160,4 +2956,12 @@
  * the structure with #pjsua_buddy_config_default() to initialize this
  * structure with default configuration.
+ *
+ * \par Python:
+ * In Python this structure is <tt>py_pjsua.Buddy_Config</tt>. However
+ * it is recommended that application instantiates the buddy config
+ * by calling:
+ * \code
+    buddy_cfg = py_pjsua.buddy_config_default()
+ * \endcode
  */
 typedef struct pjsua_buddy_config
@@ -2204,4 +3008,7 @@
  * This structure describes buddy info, which can be retrieved by calling
  * #pjsua_buddy_get_info().
+ *
+ * \par Python:
+ * This structure in Python is <tt>py_pjsua.Buddy_Info</tt>.
  */
 typedef struct pjsua_buddy_info
@@ -2249,4 +3056,9 @@
 /**
  * Set default values to the buddy config.
+ *
+ * \par Python:
+ * \code
+    buddy_cfg = py_pjsua.buddy_config_default()
+ * \endcode
  */
 PJ_INLINE(void) pjsua_buddy_config_default(pjsua_buddy_config *cfg)
@@ -2260,4 +3072,9 @@
  *
  * @return		Number of buddies.
+ *
+ * \par Python:
+ * \code
+    buddy_count = py_pjsua.get_buddy_count()
+ * \endcode
  */
 PJ_DECL(unsigned) pjsua_get_buddy_count(void);
@@ -2270,4 +3087,9 @@
  *
  * @return		Non-zero if buddy ID is valid.
+ *
+ * \par Python:
+ * \code
+    is_valid = py_pjsua.buddy_is_valid(buddy_id)
+ * \endcode
  */
 PJ_DECL(pj_bool_t) pjsua_buddy_is_valid(pjsua_buddy_id buddy_id);
@@ -2285,4 +3107,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The Python function takes no argument and returns list of buddy IDs:
+ * \code
+    [buddy_ids] = py_pjsua.enum_buddies()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_enum_buddies(pjsua_buddy_id ids[],
@@ -2296,4 +3124,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    buddy_info = py_pjsua.buddy_get_info(buddy_id)
+ * \endcode
+ * The function returns None if buddy_id is not valid.
  */
 PJ_DECL(pj_status_t) pjsua_buddy_get_info(pjsua_buddy_id buddy_id,
@@ -2305,10 +3139,16 @@
  * session immediately.
  *
- * @param cfg		Buddy configuration.
+ * @param buddy)cfg	Buddy configuration.
  * @param p_buddy_id	Pointer to receive buddy ID.
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsua_buddy_add(const pjsua_buddy_config *cfg,
+ *
+ * \par Python:
+ * The function returns (status, buddy_id) tuple:
+ * \code
+    status, buddy_id = py_pjsua.buddy_add(buddy_cfg)
+ * \endcode
+ */
+PJ_DECL(pj_status_t) pjsua_buddy_add(const pjsua_buddy_config *buddy_cfg,
 				     pjsua_buddy_id *p_buddy_id);
 
@@ -2321,4 +3161,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.buddy_del(buddy_id)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_buddy_del(pjsua_buddy_id buddy_id);
@@ -2335,4 +3180,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.buddy_subscribe_pres(buddy_id, subscribe)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id,
@@ -2344,4 +3194,9 @@
  *
  * @param verbose	Yes or no.
+ *
+ * \par Python:
+ * \code
+    py_pjsua.pres_dump()
+ * \endcode
  */
 PJ_DECL(void) pjsua_pres_dump(pj_bool_t verbose);
@@ -2371,4 +3226,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.im_send(acc_id, to, mime_type, content, msg_data, user_data)
+ * \endcode
+ * Arguments \a mime_type and \a msg_data may be set to None if not required.
  */
 PJ_DECL(pj_status_t) pjsua_im_send(pjsua_acc_id acc_id, 
@@ -2391,4 +3252,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.im_typing(acc_id, to, is_typing, msg_data)
+ * \endcode
+ * Argument \a msg_data may be set to None if not requried.
  */
 PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id, 
@@ -2410,5 +3277,5 @@
 
 /**
- * @defgroup PJSUA_LIB_MEDIA Media
+ * @defgroup PJSUA_LIB_MEDIA PJSUA-API Media Manipulation
  * @ingroup PJSUA_LIB
  * @brief Media manipulation.
@@ -2416,15 +3283,24 @@
  *
  * PJSUA has rather powerful media features, which are built around the
- * PJMEDIA conference bridge. Basically, all media termination (such as
- * calls, file players, file recorders, sound device, tone generators, etc)
+ * PJMEDIA conference bridge. Basically, all media "ports" (such as calls, WAV 
+ * players, WAV playlist, file recorders, sound device, tone generators, etc)
  * are terminated in the conference bridge, and application can manipulate
- * the interconnection between these terminations freely. If more than
- * one media terminations are terminated in the same slot, the conference
- * bridge will mix the signal automatically.
+ * the interconnection between these terminations freely. 
+ *
+ * The conference bridge provides powerful switching and mixing functionality
+ * for application. With the conference bridge, each conference slot (e.g. 
+ * a call) can transmit to multiple destinations, and one destination can
+ * receive from multiple sources. If more than one media terminations are 
+ * terminated in the same slot, the conference bridge will mix the signal 
+ * automatically.
  *
  * Application connects one media termination/slot to another by calling
  * #pjsua_conf_connect() function. This will establish <b>unidirectional</b>
- * media flow from the source termination to the sink termination. For
- * example, to stream a WAV file to remote call, application may use
+ * media flow from the source termination to the sink termination. To
+ * establish bidirectional media flow, application wound need to make another
+ * call to #pjsua_conf_connect(), this time inverting the source and 
+ * destination slots in the parameter.
+ *
+ * For example, to stream a WAV file to remote call, application may use
  * the following steps:
  *
@@ -2502,4 +3378,12 @@
  * when calling #pjsua_init(). Application MUST initialize this structure
  * by calling #pjsua_media_config_default().
+ *
+ * \par Python:
+ * This data type in Python is <tt>py_pjsua.Media_Config</tt>. To create
+ * an object of this type, it is recommended to call 
+ * <tt>py_pjsua.media_config_default()</tt> function instead:
+ * \code
+    media_cfg = py_pjsua.media_config_default()
+ * \endcode
  */
 struct pjsua_media_config
@@ -2638,4 +3522,9 @@
  *
  * @param cfg	The media config to be initialized.
+ *
+ * \par Python:
+ * \code
+    media_cfg = py_pjsua.media_config_default()
+ * \endcode
  */
 PJ_INLINE(void) pjsua_media_config_default(pjsua_media_config *cfg)
@@ -2683,4 +3572,7 @@
  * has been registered into the conference bridge. Application can query
  * this info by calling #pjsua_conf_get_port_info().
+ *
+ * \par Python:
+ * In Python, this type is <tt>py_pjsua.Conf_Port_Info</tt>.
  */
 typedef struct pjsua_conf_port_info
@@ -2718,4 +3610,7 @@
  * This structure holds information about custom media transport to
  * be registered to pjsua.
+ *
+ * \par Python:
+ * Not applicable.
  */
 typedef struct pjsua_media_transport
@@ -2741,4 +3636,9 @@
  *
  * @return		Maximum number of ports in the conference bridge.
+ *
+ * \par Python:
+ * \code
+    port_count = py_pjsua.conf_get_max_ports()
+ * \endcode
  */
 PJ_DECL(unsigned) pjsua_conf_get_max_ports(void);
@@ -2749,4 +3649,9 @@
  *
  * @return		The number.
+ *
+ * \par Python:
+ * \code
+    count = py_pjsua.conf_get_active_ports()
+ * \endcode
  */
 PJ_DECL(unsigned) pjsua_conf_get_active_ports(void);
@@ -2762,4 +3667,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The Python functions returns list of conference port Ids:
+ * \code
+    [port_ids] = py_pjsua.enum_conf_ports()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_enum_conf_ports(pjsua_conf_port_id id[],
@@ -2770,10 +3681,16 @@
  * Get information about the specified conference port
  *
- * @param id		Port identification.
+ * @param port_id	Port identification.
  * @param info		Pointer to store the port info.
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsua_conf_get_port_info( pjsua_conf_port_id id,
+ *
+ * \par Python:
+ * \code
+    port_info = py_pjsua.conf_get_port_info(port_id)
+ * \endcode
+ * The function will return None if \a port_id is not valid.
+ */
+PJ_DECL(pj_status_t) pjsua_conf_get_port_info( pjsua_conf_port_id port_id,
 					       pjsua_conf_port_info *info);
 
@@ -2792,4 +3709,7 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * Not applicable (for now)
  */
 PJ_DECL(pj_status_t) pjsua_conf_add_port(pj_pool_t *pool,
@@ -2803,9 +3723,14 @@
  * to #pjsua_conf_add_port().
  *
- * @param id		The slot id of the port to be removed.
- *
- * @return		PJ_SUCCESS on success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsua_conf_remove_port(pjsua_conf_port_id id);
+ * @param port_id	The slot id of the port to be removed.
+ *
+ * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.conf_remove_port(port_id)
+ * \endcode
+ */
+PJ_DECL(pj_status_t) pjsua_conf_remove_port(pjsua_conf_port_id port_id);
 
 
@@ -2825,4 +3750,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.conf_connect(source, sink)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_conf_connect(pjsua_conf_port_id source,
@@ -2837,4 +3767,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.conf_disconnect(source, sink)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_conf_disconnect(pjsua_conf_port_id source,
@@ -2851,4 +3786,7 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * Not implemented (yet)
  */
 PJ_DECL(pj_status_t) pjsua_conf_adjust_tx_level(pjsua_conf_port_id slot,
@@ -2864,4 +3802,7 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * Not implemented (yet)
  */
 PJ_DECL(pj_status_t) pjsua_conf_adjust_rx_level(pjsua_conf_port_id slot,
@@ -2882,13 +3823,11 @@
  *
  * @return		PJ_SUCCESS on success.
+ *
+ * \par Python:
+ * Not implemented (yet)
  */
 PJ_DECL(pj_status_t) pjsua_conf_get_signal_level(pjsua_conf_port_id slot,
 						 unsigned *tx_level,
 						 unsigned *rx_level);
-
-/**
- * 
- */
-
 
 
@@ -2909,4 +3848,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function returns (status, id) tuple:
+ * \code
+    status, id = py_pjsua.player_create(filename, options)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_player_create(const pj_str_t *filename,
@@ -2929,4 +3874,7 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * Not implemented yet.
  */
 PJ_DECL(pj_status_t) pjsua_playlist_create(const pj_str_t file_names[],
@@ -2942,4 +3890,9 @@
  *
  * @return		Conference port ID associated with this player.
+ *
+ * \par Python:
+ * \code
+    port_id = py_pjsua.player_get_conf_port(id)
+ * \endcode
  */
 PJ_DECL(pjsua_conf_port_id) pjsua_player_get_conf_port(pjsua_player_id id);
@@ -2953,4 +3906,7 @@
  *
  * @return		PJ_SUCCESS on success.
+ *
+ * \par Python:
+ * Not applicable.
  */
 PJ_DECL(pj_status_t) pjsua_player_get_port(pjsua_recorder_id id,
@@ -2965,4 +3921,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.player_set_pos(id, samples)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_player_set_pos(pjsua_player_id id,
@@ -2977,4 +3938,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.player_destroy(id)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_player_destroy(pjsua_player_id id);
@@ -3009,4 +3975,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status, id = py_pjsua.recorder_create(filename, enc_type, enc_param, max_size, options)
+ * \endcode
+ * The \a enc_param is a string in Python.
  */
 PJ_DECL(pj_status_t) pjsua_recorder_create(const pj_str_t *filename,
@@ -3024,4 +3996,9 @@
  *
  * @return		Conference port ID associated with this recorder.
+ *
+ * \par Python:
+ * \code
+    port_id = py_pjsua.recorder_get_conf_port(id)
+ * \endcode
  */
 PJ_DECL(pjsua_conf_port_id) pjsua_recorder_get_conf_port(pjsua_recorder_id id);
@@ -3035,4 +4012,7 @@
  *
  * @return		PJ_SUCCESS on success.
+ *
+ * \par Python:
+ * Not applicable.
  */
 PJ_DECL(pj_status_t) pjsua_recorder_get_port(pjsua_recorder_id id,
@@ -3046,4 +4026,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.recorder_destroy(id)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_recorder_destroy(pjsua_recorder_id id);
@@ -3063,4 +4048,12 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ *
+ * \par Python:
+ * The function returns list of sound device info:
+ * \code
+    [dev_infos] = py_pjsua.enum_snd_devs()
+ * \endcode
+ *
  */
 PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_snd_dev_info info[],
@@ -3080,4 +4073,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * The function takes no argument and return a tuple:
+ * \code
+    capture_dev, playback_dev = py_pjsua.get_snd_dev()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_get_snd_dev(int *capture_dev,
@@ -3093,4 +4092,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.set_snd_dev(capture_dev, playback_dev)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_set_snd_dev(int capture_dev,
@@ -3104,4 +4108,9 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.set_null_snd_dev()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_set_null_snd_dev(void);
@@ -3115,4 +4124,7 @@
  *			so that application can connect this to it's own
  *			sound device or master port.
+ *
+ * \par Python:
+ * Not applicable (for now).
  */
 PJ_DECL(pjmedia_port*) pjsua_set_no_snd_dev(void);
@@ -3128,4 +4140,9 @@
  *
  * @return		PJ_SUCCESS on success.
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.set_ec(tail_ms, options)
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_set_ec(unsigned tail_ms, unsigned options);
@@ -3139,4 +4156,9 @@
  *
  * @return		PJ_SUCCESS on success.
+ *
+ * \par Python:
+ * \code
+    tail_ms = py_pjsua.get_ec_tail()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_get_ec_tail(unsigned *p_tail_ms);
@@ -3157,4 +4179,10 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * This function takes no argument and returns list of codec infos:
+ * \code
+    [codec_info] = py_pjsua.enum_codecs()
+ * \endcode
  */
 PJ_DECL(pj_status_t) pjsua_enum_codecs( pjsua_codec_info id[],
@@ -3165,11 +4193,18 @@
  * Change codec priority.
  *
- * @param id		Codec ID.
+ * @param codec_id	Codec ID, which is a string that uniquely identify
+ *			the codec (such as "speex/8000"). Please see pjsua
+ *			manual or pjmedia codec reference for details.
  * @param priority	Codec priority, 0-255, where zero means to disable
  *			the codec.
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsua_codec_set_priority( const pj_str_t *id,
+ *
+ * \par Python:
+ * \code
+    status = py_pjsua.codec_set_priority(codec_id, priority)
+ * \endcode
+ */
+PJ_DECL(pj_status_t) pjsua_codec_set_priority( const pj_str_t *codec_id,
 					       pj_uint8_t priority );
 
@@ -3178,10 +4213,16 @@
  * Get codec parameters.
  *
- * @param id		Codec ID.
+ * @param codec_id	Codec ID.
  * @param param		Structure to receive codec parameters.
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsua_codec_get_param( const pj_str_t *id,
+ *
+ * \par Python:
+ * The Python function is experimental:
+ * \code
+    codec_param = py_pjsua.codec_get_param(codec_id)
+ * \endcode
+ */
+PJ_DECL(pj_status_t) pjsua_codec_get_param( const pj_str_t *codec_id,
 					    pjmedia_codec_param *param );
 
@@ -3190,10 +4231,17 @@
  * Set codec parameters.
  *
- * @param id		Codec ID.
+ * @param codec_id	Codec ID.
  * @param param		Codec parameter to set.
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *id,
+ *
+ * \par Python:
+ * The Python function is experimental:
+ * \code
+    status = py_pjsua.codec_set_param(codec_id, param)
+ * \endcode
+
+ */
+PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *codec_id,
 					    const pjmedia_codec_param *param);
 
@@ -3210,4 +4258,7 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * Not implemented yet.
  */
 PJ_DECL(pj_status_t) 
@@ -3227,4 +4278,7 @@
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
+ *
+ * \par Python:
+ * Note applicable.
  */
 PJ_DECL(pj_status_t) 
@@ -3240,11 +4294,10 @@
 
 
+/**
+ * @}
+ */
+
 PJ_END_DECL
 
 
-/**
- * @}
- */
-
-
 #endif	/* __PJSUA_H__ */
Index: /pjproject/trunk/pjsip/src/pjsip/sip_transport_udp.c
===================================================================
--- /pjproject/trunk/pjsip/src/pjsip/sip_transport_udp.c	(revision 917)
+++ /pjproject/trunk/pjsip/src/pjsip/sip_transport_udp.c	(revision 918)
@@ -80,5 +80,6 @@
 
     /* Reset pool. */
-    pj_pool_reset(pool);
+    //note: already done by caller
+    //pj_pool_reset(pool);
 
     rdata = pj_pool_zalloc(pool, sizeof(pjsip_rx_data));
