Updated doxygen documentation for the website

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

11 files changed, 73 insertions, 16 deletions

diff --git a/pjlib/include/pj/doxygen.h b/pjlib/include/pj/doxygen.h
index 51a69777..855d3312 100644
--- a/pjlib/include/pj/doxygen.h
+++ b/pjlib/include/pj/doxygen.h
@@ -55,7 +55,7 @@
  *
  * @subsection doc_ver_subsec Version
  *
- * This document corresponds to PJLIB version 0.5.7.6.
+ * This document corresponds to PJLIB version 0.5.8.
  *
  *
  * @subsection find_samples_subsec How to Read This Document
@@ -457,6 +457,14 @@
  *
  * @section build_sys_install_sec Build and Installation
  *
+ * \note
+ * <b>The most up-to-date information on building and installing PJLIB
+ *  should be found in the website, under "Getting Started" document.
+ *  More over, the new PJLIB build system is now based on autoconf,
+ *  so some of the information here might not be relevant anymore 
+ *  (although most still are, since the autoconf script still use
+ *  the old Makefile system as the backend).</b>
+ *
  * @subsection build_sys_install_win32_sec Visual Studio
  *
  * The PJLIB Visual Studio workspace supports the building of PJLIB
@@ -793,6 +801,13 @@ obj-$(CONFIG_GENERIC_ISA_DMA) += dma.o
 /**
  * @page porting_pjlib_pg Porting PJLIB
  *
+ * \note
+ * <b>Since version 0.5.8, PJLIB build system is now based on autoconf, so
+ * most of the time we shouldn't need to apply the tweakings below to get
+ * PJLIB working on a new platform. However, since the autoconf build system
+ * still uses the old Makefile build system, the information below may still
+ * be useful for reference.
+ * </b>
  *
  * @section new_arch_sec Porting to New CPU Architecture
  *
diff --git a/pjlib/include/pj/pool.h b/pjlib/include/pj/pool.h
index 48c00e8e..61c3de09 100644
--- a/pjlib/include/pj/pool.h
+++ b/pjlib/include/pj/pool.h
@@ -101,7 +101,8 @@ PJ_BEGIN_DECL
  * The result of PJLIB's memory design and careful implementation is a
  * memory allocation strategy that can speed-up the memory allocations
  * and deallocations by up to <b>30 times</b> compared to standard
- * malloc()/free()!
+ * malloc()/free() (more than 150 million allocations per second on a
+ * P4/3.0GHz Linux machine).
  *
  * (Note: your mileage may vary, of course. You can see how much PJLIB's
  *  pool improves the performance over malloc()/free() in your target
diff --git a/pjmedia/include/pjmedia/doxygen.h b/pjmedia/include/pjmedia/doxygen.h
index c9bef719..f1765bc5 100644
--- a/pjmedia/include/pjmedia/doxygen.h
+++ b/pjmedia/include/pjmedia/doxygen.h
@@ -492,6 +492,15 @@
     is recommended.\n
     Screenshots on WinXP: \image html siprtp.jpg "siprtp screenshot on WinXP"
 
+  - @ref page_pjmedia_samples_tonegen_c\n
+    This is a simple program to generate a tone and write the samples to
+    a raw PCM file. The main purpose of this file is to analyze the
+    quality of the tones/sine wave generated by PJMEDIA tone/sine wave
+    generator.
+
+  - @ref page_pjmedia_samples_aectest_c\n
+    Play a file to speaker, run AEC, and record the microphone input
+    to see if echo is coming.
  */
 
 /**
diff --git a/pjsip-apps/src/samples/tonegen.c b/pjsip-apps/src/samples/tonegen.c
index de8925b1..a703a7bb 100644
--- a/pjsip-apps/src/samples/tonegen.c
+++ b/pjsip-apps/src/samples/tonegen.c
@@ -16,6 +16,21 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
  */
+
+/**
+ * \page page_pjmedia_samples_tonegen_c Samples: Sine Wave/Dual-Tone Generation
+ *
+ * This is a simple program to generate a tone and write the samples to
+ * a raw PCM file. The main purpose of this file is to analyze the
+ * quality of the tones/sine wave generated by PJMEDIA tone/sine wave
+ * generator.
+ *
+ * This file is pjsip-apps/src/samples/tonegen.c
+ *
+ * \includelineno tonegen.c
+ */
+
+
 #include <pjmedia.h>
 #include <pjlib.h>
 
diff --git a/pjsip/docs/doxygen.h b/pjsip/docs/doxygen.h
index 604284f6..89deb47f 100644
--- a/pjsip/docs/doxygen.h
+++ b/pjsip/docs/doxygen.h
@@ -28,8 +28,9 @@
  */
 
 /**
+  \n
 
-  @mainpage PJSIP
+  @mainpage PJSIP - Open Source SIP Stack
 
   \n
   \n
@@ -118,7 +119,7 @@
   \n
   @subsection doc_ver Version
 
-  This document corresponds to PJSIP version 0.5.6.
+  This document corresponds to PJSIP version 0.5.8.
 
   \n
   @subsection doc_how_to_read How to Read This Document
@@ -216,6 +217,12 @@
     is recommended.\n
     Screenshots on WinXP: \image html siprtp.jpg "siprtp screenshot on WinXP"
 
+  - @ref page_pjsip_perf_c\n
+    This sample contains a complete implementation of a SIP performance
+    measurement tool. Unlike other tool such SIPp, pjsip-perf is geared
+    more towards finding the performance of an endpoint by flooding the
+    endpoint with some requests and time the completion of the requests.\n
+    Screenshots on Linux console: \image html pjsip-perf.jpg "pjsip-perf screenshot on Linux"
  */
 
 /**
@@ -254,7 +261,7 @@
  */
 
 /**
- * \page page_pjmedia_samples_siprtp_c Samples: Using SIP and Custom RTP/RTCP to Monitor Quality
+ * \page page_pjmedia_samples_siprtp_c Samples: siprtp - SIP with RTCP Quality Monitoring
  *
  * This source is an example to demonstrate using SIP and RTP/RTCP framework
  * to measure the network quality/impairment from the SIP call. This
@@ -274,3 +281,18 @@
  * \includelineno siprtp.c
  */
 
+/**
+ * \page page_pjsip_perf_c Samples: pjsip-perf - SIP Performance Benchmarking Tool
+ *
+ * This sample contains a complete implementation of a SIP performance
+ * measurement tool. Unlike other tool such SIPp, pjsip-perf is geared
+ * more towards finding the performance of an endpoint by flooding the
+ * endpoint with some requests and time the completion of the requests.
+ *
+ * The source code of the file is pjsip-apps/src/samples/pjsip-perf.c
+ *
+ * Screenshots on Linux console: \image html pjsip-perf.jpg
+ *
+ * \includelineno pjsip-perf.c
+ */
+
diff --git a/pjsip/docs/pjsip-perf.jpg b/pjsip/docs/pjsip-perf.jpg
new file mode 100644
index 00000000..2e1fd3c9
--- /dev/null
+++ b/pjsip/docs/pjsip-perf.jpg
diff --git a/pjsip/docs/siprtp.jpg b/pjsip/docs/siprtp.jpg
new file mode 100644
index 00000000..975f1fad
--- /dev/null
+++ b/pjsip/docs/siprtp.jpg
diff --git a/pjsip/include/pjsip/sip_endpoint.h b/pjsip/include/pjsip/sip_endpoint.h
index e6632042..aed4d8a2 100644
--- a/pjsip/include/pjsip/sip_endpoint.h
+++ b/pjsip/include/pjsip/sip_endpoint.h
@@ -244,9 +244,7 @@ PJ_DECL(pjsip_transaction*) pjsip_endpt_find_tsx( pjsip_endpoint *endpt,
 
 /**
  * Register the transaction to the endpoint's transaction table.
- * Before the transaction is registered, it must have been initialized as
- * either UAS or UAC by calling #pjsip_tsx_init_uac or #pjsip_tsx_init_uas.
- * This function, like all other endpoint functions, is thread safe.
+ * This function should only be used internally by the stack.
  *
  * @param endpt	    The SIP endpoint.
  * @param tsx	    The transaction.
@@ -255,11 +253,8 @@ PJ_DECL(void) pjsip_endpt_register_tsx( pjsip_endpoint *endpt,
 					pjsip_transaction *tsx);
 
 /**
- * Forcefull destroy the transaction.
- * The only time where application needs to call this function is when the
- * transaction fails to initialize in #pjsip_tsx_init_uac or
- * #pjsip_tsx_init_uas. For other cases. the transaction will be destroyed
- * automaticly by endpoint.
+ * Forcefull destroy the transaction. This function should only be used
+ * internally by the stack.
  *
  * @param endpt	    The endpoint.
  * @param tsx	    The transaction to destroy.
diff --git a/pjsip/include/pjsip/sip_msg.h b/pjsip/include/pjsip/sip_msg.h
index 08f8e88e..b27b2708 100644
--- a/pjsip/include/pjsip/sip_msg.h
+++ b/pjsip/include/pjsip/sip_msg.h
@@ -910,7 +910,7 @@ pjsip_generic_string_hdr_init( pj_pool_t *pool,
  * very short (for example, creating the header in the stack to be passed
  * as argument to a function which will copy the header).
  *
- * @param pool	    The pool.
+ * @param h	    The header to be initialized.
  * @param hname	    The header name to be assigned to the header, or NULL to
  *		    assign the header name with some string.
  * @param hvalue    Optional string to be assigned as the value.
diff --git a/pjsip/include/pjsip/sip_transport.h b/pjsip/include/pjsip/sip_transport.h
index ec371f0f..f0f915cd 100644
--- a/pjsip/include/pjsip/sip_transport.h
+++ b/pjsip/include/pjsip/sip_transport.h
@@ -360,7 +360,7 @@ typedef struct pjsip_tx_data_op_key
  * this buffer will be destroyed.
  *
  * A transaction object normally will add reference counter to this buffer
- * when application calls #pjsip_tsx_on_tx_msg, because it needs to keep the
+ * when application calls #pjsip_tsx_send_msg, because it needs to keep the
  * message for retransmission. The transaction will release the reference
  * counter once its state has reached final state.
  */
diff --git a/pjsip/include/pjsip/sip_util.h b/pjsip/include/pjsip/sip_util.h
index d2b46be1..2b77e469 100644
--- a/pjsip/include/pjsip/sip_util.h
+++ b/pjsip/include/pjsip/sip_util.h
@@ -395,7 +395,7 @@ PJ_DECL(pj_status_t) pjsip_endpt_respond( pjsip_endpoint *endpt,
  * Send outgoing request and initiate UAC transaction for the request.
  * This is an auxiliary function to be used by application to send arbitrary
  * requests outside a dialog. To send a request within a dialog, application
- * should use #pjsip_dlg_send_msg instead.
+ * should use #pjsip_dlg_send_request instead.
  *
  * @param endpt	    The endpoint instance.
  * @param tdata	    The transmit data to be sent.