Re #1134 (misc fixes): fixed various doxygen warnings, as well as added overview section in pjmedia documentation

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

13 files changed, 143 insertions, 62 deletions

diff --git a/pjlib/include/pj/config_site_sample.h b/pjlib/include/pj/config_site_sample.h
index 2751ab22..0c7832f0 100644
--- a/pjlib/include/pj/config_site_sample.h
+++ b/pjlib/include/pj/config_site_sample.h
@@ -373,13 +373,12 @@
  * than native fdset_t and will trigger assertion on sock_select.c.
  */
 #   define PJ_IOQUEUE_MAX_HANDLES	32
+#   define PJ_CRC32_HAS_TABLES		0
 #   define PJSIP_MAX_TSX_COUNT		15
 #   define PJSIP_MAX_DIALOG_COUNT	15
 #   define PJSIP_UDP_SO_SNDBUF_SIZE	4000
 #   define PJSIP_UDP_SO_RCVBUF_SIZE	4000
-#   define PJMEDIA_HAS_LARGE_FILTER	0
-#   define PJMEDIA_HAS_SMALL_FILTER	0
-
+#   define PJMEDIA_HAS_ALAW_ULAW_TABLE	0
 
 #elif defined(PJ_CONFIG_MAXIMUM_SPEED)
 #   define PJ_SCANNER_USE_BITWISE	0
diff --git a/pjmedia/include/pjmedia-audiodev/audiodev.h b/pjmedia/include/pjmedia-audiodev/audiodev.h
index 09c6209b..ba28bc0f 100644
--- a/pjmedia/include/pjmedia-audiodev/audiodev.h
+++ b/pjmedia/include/pjmedia-audiodev/audiodev.h
@@ -455,7 +455,7 @@ PJ_DECL(const char*) pjmedia_aud_dev_cap_name(pjmedia_aud_dev_cap cap,
  *
  * @param param		The structure.
  * @param cap		The audio capability which value is to be set.
- * @param value		Pointer to value. Please see the type of value to
+ * @param pval		Pointer to value. Please see the type of value to
  *			be supplied in the pjmedia_aud_dev_cap documentation.
  *
  * @return		PJ_SUCCESS on successful operation or the appropriate
@@ -473,7 +473,7 @@ PJ_DECL(pj_status_t) pjmedia_aud_param_set_cap(pjmedia_aud_param *param,
  *
  * @param param		The structure.
  * @param cap		The audio capability which value is to be retrieved.
- * @param value		Pointer to value. Please see the type of value to
+ * @param pval		Pointer to value. Please see the type of value to
  *			be supplied in the pjmedia_aud_dev_cap documentation.
  *
  * @return		PJ_SUCCESS on successful operation or the appropriate
diff --git a/pjmedia/include/pjmedia-codec/amr_helper.h b/pjmedia/include/pjmedia-codec/amr_helper.h
index 8cc232eb..e8df0a0a 100644
--- a/pjmedia/include/pjmedia-codec/amr_helper.h
+++ b/pjmedia/include/pjmedia-codec/amr_helper.h
@@ -597,7 +597,7 @@ const pj_uint16_t pjmedia_codec_amrwb_bitrates[9] =
 
 
 /**
- * This structure describes AMR frame info, to be fitted into @pjmedia_frame 
+ * This structure describes AMR frame info, to be fitted into #pjmedia_frame
  * bit info.
  */
 #pragma pack(1)
@@ -712,9 +712,8 @@ PJ_INLINE(pj_int8_t) pjmedia_codec_amr_get_mode2(pj_bool_t amrnb,
  *   'setting' by setting/resetting field 'reorder'.
  * - align left the start bit (make the start_bit to be 0).
  *
- * @param amr_nb    Set PJ_TRUE for AMR-NB and PJ_FALSE for AMR-WB.
  * @param in	    Input frame.
- * @param setting   Settings, see @pjmedia_codec_amr_pack_setting.
+ * @param setting   Settings, see #pjmedia_codec_amr_pack_setting.
  * @param out	    Output frame.
  *
  * @return	    PJ_SUCCESS on success.
@@ -852,7 +851,7 @@ PJ_INLINE(pj_status_t) pjmedia_codec_amr_predecode(
  *
  * @param frames    AMR frames to be packed.
  * @param nframes   Number of frames to be packed.
- * @param setting   Settings, see @pjmedia_codec_amr_pack_setting.
+ * @param setting   Settings, see #pjmedia_codec_amr_pack_setting.
  * @param pkt	    Payload.
  * @param pkt_size  Payload size, as input this specifies payload maximum size,
  *		    as output this specifies payload packed size.
@@ -1069,7 +1068,7 @@ PJ_INLINE (pj_status_t) pjmedia_codec_amr_pack(
  * @param pkt	    Payload.
  * @param pkt_size  Payload size.
  * @param ts	    Base timestamp.
- * @param setting   Settings, see @pjmedia_codec_amr_pack_setting.
+ * @param setting   Settings, see #pjmedia_codec_amr_pack_setting.
  * @param frames    Frames parsed.
  * @param nframes   Number of frames parsed.
  * @param cmr	    Change Mode Request message for local encoder.
diff --git a/pjmedia/include/pjmedia/conference.h b/pjmedia/include/pjmedia/conference.h
index e12f348b..9934489a 100644
--- a/pjmedia/include/pjmedia/conference.h
+++ b/pjmedia/include/pjmedia/conference.h
@@ -239,7 +239,7 @@ PJ_DECL(pj_status_t) pjmedia_conf_add_port( pjmedia_conf *conf,
 
 /**
  * <i><b>Warning:</b> This API has been deprecated since 1.3 and will be
- * removed in the future release, use #PJMEDIA_SPLITCOMB instead.</i>
+ * removed in the future release, use @ref PJMEDIA_SPLITCOMB instead.</i>
  *
  * Create and add a passive media port to the conference bridge. Unlike
  * "normal" media port that is added with #pjmedia_conf_add_port(), media
diff --git a/pjmedia/include/pjmedia/delaybuf.h b/pjmedia/include/pjmedia/delaybuf.h
index 70cff90a..ec87c0fc 100644
--- a/pjmedia/include/pjmedia/delaybuf.h
+++ b/pjmedia/include/pjmedia/delaybuf.h
@@ -79,7 +79,7 @@ typedef struct pjmedia_delay_buf pjmedia_delay_buf;
  *			    in ms, if this value is negative or less than 
  *			    one frame time, default maximum delay used is
  *			    400 ms.
- * @param option	    Option flags, must be zero for now.
+ * @param options	    Option flags, must be zero for now.
  * @param p_b		    Pointer to receive the delay buffer instance.
  *
  * @return		    PJ_SUCCESS if the delay buffer has been
diff --git a/pjmedia/include/pjmedia/doxygen.h b/pjmedia/include/pjmedia/doxygen.h
index 261d7611..a2b03f36 100644
--- a/pjmedia/include/pjmedia/doxygen.h
+++ b/pjmedia/include/pjmedia/doxygen.h
@@ -32,49 +32,119 @@
  */
 
 /**
- * @mainpage PJMEDIA and PJMEDIA-CODEC
+ * @mainpage PJMEDIA
  *
  * \n
- * @section intro_sec PJMEDIA
+ * @section intro2 Introduction to PJMEDIA
+ *
+ * PJMEDIA is a fully featured media stack, distributed under Open Source/GPL
+ * terms, and featuring small footprint and good extensibility and excellent
+ * portability. Here are some brief overview of PJMEDIA benefits.
+ *
+ * @subsection benefit Benefits
+ * @subsubsection full_feature Many Features
+ * PJMEDIA has many features, and rather than to list them all here, please
+ * see the <A HREF="modules.htm"><b>Modules</b></A> page for more info.
+ *
+ * Video is planned to arrive at version 2.
+ *
+ * @subsubsection portable Excellent Portability
+ * It's been ported to all desktop systems and many mobile platforms including
+ * Symbian, Windows Mobile, iPhone, and Android. Thanks to its zero thread
+ * design, users have been able to run PJMEDIA on deeply embedded platforms,
+ * even without operating systems (those typically found in DSP platforms).
+ * Except the echo suppressor, all other PJMEDIA components have fixed point
+ * implementation, which makes it ideal for embedded systems which lack FPU.
+ * PJMEDIA also has tiny footprint, as explained below
+ *
+ * @subsubsection footprint Tiny Footprint
+ * Lets not talk about less meaningful and potentially misleading term such as
+ * core footprint, and instead here is the footprint of all components
+ * typically used to build a full streaming media:
+ *
+ * \verbatim
+Category        Component       text    data    bss     dec     filename
+-------------------------------------------------------------------------------
+Core            Error subsystem 135     0       0       135     errno.o
+Core            Endpoint        4210    4       4       4218    endpoint.o
+Core            Port framework  652     0       0       652     port.o
+Core            Codec framework 6257    0       0       6257    codec.o
+Codec           Alaw/ulaw conv. 1060    16      0       1076    alaw_ulaw.o
+Codec           G.711           3298    128     96      3522    g711.o
+Codec           PLC             883     24      0       907     plc_common.o
+Codec           PLC             7130    0       0       7130    wsola.o
+Session         Stream          12222   0       1920    14142   stream.o
+Transport       RTCP            3732    0       0       3732    rtcp.o
+Transport       RTP             2568    0       0       2568    rtp.o
+Transport       UDP             6612    96      0       6708    transport_udp.o
+Transport       Jitter buffer   6473    0       0       6473    jbuf.o
+-------------------------------------------------------------------------------
+TOTAL                          55,232   268    2,020    57,520
+
+ \endverbatim
+ * The 56KB are for media streaming components, complete with codec, RTP, and
+ * RTCP. The footprint above was done for PJSIP version 1.8.2 on a Linux x86
+ * machine, using footprintopimization as explained in PJSIP FAQ. Numbers are
+ * in bytes.
+ *
+ * @subsubsection quality Good Quality
+ * PJMEDIA supports wideband, ultra-wideband, and beyond, as well as multiple
+ * audio channels. The jitter buffer has been proven to work on lower
+ * bandwidth links such as 3G, and to some extent, Edge and GPRS. We've grown
+ * our own algorithm to compensate for packet losses and clock drifts in audio
+ * transmission, as well as feature to use codec's built in PLC if available.
+ *
+ * @subsubsection hw Hardware Support
+ * PJMEDIA supports hardware, firmware, or other built-in feature that comes
+ * with the device. These are crucial for mobile devices to allow the best
+ * use of the very limited CPU and battery power of the device. Among other
+ * things, device's on-board codec and echo cancellation may be used if
+ * available.
+ *
+ * @subsubsection extensible Extensible
+ * Despite its tiny footprint, PJMEDIA uses a flexible port concept, which is
+ * adapted from filter based concept found in other media framework. It is not
+ * as flexible as those found in Direct Show or gstreamer (and that would be
+ * unnecessary since it serves different purpose), but it's flexible enough
+ * to allow components to be assembled one after another to achieve certain
+ * task, and easy creation of such components by application and interconnect
+ * them to the rest of the framework.
+ *
+ * @subsubsection doc (Fairly Okay) Documentation
+ * We understand that any documentation can always be improved, but we put
+ * a lot of efforts in creating and maintaining our documentation, because
+ * we know it matters.
  *
- * PJMEDIA is a rather complete media stack, distributed under Open Source/GPL
- * terms, and featuring small footprint and good extensibility and portability.
- *
- * Please click the <A HREF="modules.htm"><b>Table of Contents</b></A> link on top
- * of this page to get the complete features currently present in PJMEDIA.
+ * \n
+ * @subsection org1 Organization
  *
- * Also please read the documentation about @ref PJMEDIA_PORT
- * which is a major concept that is used for implementing many objects in 
- * the library.
+ * At the top-most level, PJMEDIA library suite contains the following
+ * libraries.
  *
- * \n
- * @section pjmedia_codec_sec PJMEDIA-CODEC
+ * @subsubsection libpjmedia PJMEDIA
+ * This contains all main media components. Please see the
+ * <A HREF="modules.htm"><b>Modules</b></A> page for complete list of
+ * components that PJMEDIA provides.
  *
+ * @subsubsection libpjmediacodec PJMEDIA Codec
  * PJMEDIA-CODEC is a static library containing various codec implementations,
  * wrapped into PJMEDIA codec framework. The static library is designed as
  * such so that only codecs that are explicitly initialized are linked with 
  * the application, therefore keeping the application size in control.
  *
- * Please see @ref pjmedia_codec_page on how to use the codec in 
- * PJMEDIA-CODEC.
- *
- * \n
- * @section main_page_get_start_sec Getting Started
- *
- * For those who likes to just get start coding, the @ref getting_started_pjmedia
- * may be a good place to start.
- *
- * The @ref page_pjmedia_samples page describes some examples that are available
- * in the source tree.
+ * Please see @ref PJMEDIA_CODEC for more info.
  *
+ * @subsubsection libpjmediaaudiodev PJMEDIA Audio Device
+ * PJMEDIA-Audiodev is audio device framework and abstraction library. Please
+ * see @ref audio_device_api for more info.
  *
  * \n
- * @section pjmedia_lic Copying and Acknowledgements
- *
- * PJMEDIA and PJMEDIA-CODEC contains various parts obtained from other
- * places, and each of these would have their own licensing terms.
- * Please see @ref lic_stuffs page for details.
- *
+ * @section pjmedia_concepts PJMEDIA Key Concepts
+ * Below are some key concepts in PJMEDIA:
+ *  - @ref PJMEDIA_PORT
+ *  - @ref PJMEDIA_PORT_CLOCK
+ *  - @ref PJMEDIA_TRANSPORT
+ *  - @ref PJMEDIA_SESSION
  */
 
 
diff --git a/pjmedia/include/pjmedia/port.h b/pjmedia/include/pjmedia/port.h
index ccfff18d..c4605756 100644
--- a/pjmedia/include/pjmedia/port.h
+++ b/pjmedia/include/pjmedia/port.h
@@ -37,25 +37,37 @@
   
   @subsection The Media Port
   A media port (represented with pjmedia_port "class") provides a generic
-  and extensible framework for implementing media terminations. A media
+  and extensible framework for implementing media elements. Media element
+  itself could be a media source, sink, or processing element. A media
   port interface basically has the following properties:
   - media port information (pjmedia_port_info) to describe the
   media port properties (sampling rate, number of channels, etc.),
-  - pointer to function to acquire frames from the port (<tt>get_frame()
-  </tt> interface), which will be called by #pjmedia_port_get_frame()
-  public API, and
-  - pointer to function to store frames to the port (<tt>put_frame()</tt>
-  interface) which will be called by #pjmedia_port_put_frame() public
-  API.
+  - optional pointer to function to acquire frames from the port (the
+    <tt>get_frame() </tt> interface), which will be called by
+    #pjmedia_port_get_frame() public API, and
+  - optional pointer to function to store frames to the port (the
+    <tt>put_frame()</tt> interface) which will be called by
+    #pjmedia_port_put_frame() public API.
+
+  The <tt>get_frame()</tt> and <tt>put_frame()</tt> interface of course
+  would only need to be implemented if the media port emits and/or takes
+  media frames respectively.
   
-  Media ports are passive "objects". Applications (or other PJMEDIA 
-  components) must actively calls #pjmedia_port_get_frame() or 
-  #pjmedia_port_put_frame() from/to the media port in order to retrieve/
-  store media frames.
+  Media ports are passive "objects". By default, there is no worker thread
+  to run the media flow. Applications (or other PJMEDIA
+  components, as explained in @ref PJMEDIA_PORT_CLOCK) must actively call
+  #pjmedia_port_get_frame() or #pjmedia_port_put_frame() from/to the media
+  port in order to retrieve/store media frames.
   
   Some media ports (such as @ref PJMEDIA_CONF and @ref PJMEDIA_RESAMPLE_PORT)
-  may be interconnected with each other, while some
+  may be interconnected with (or encapsulate) other port, to perform the
+  combined task of the ports, while some
   others represent the ultimate source/sink termination for the media. 
+  Interconnection means the upstream media port will call <tt>get_frame()</tt>
+  and <tt>put_frame()</tt> to its downstream media port. For this to happen,
+  the media ports need to have the same format, where format is defined as
+  combination of sample format, clock rate, channel count, bits per sample,
+  and samples per frame for audio media.
 
 
   @subsection port_clock_ex1 Example: Manual Resampling
diff --git a/pjmedia/include/pjmedia/rtcp_xr.h b/pjmedia/include/pjmedia/rtcp_xr.h
index 8ad27958..63f0aa56 100644
--- a/pjmedia/include/pjmedia/rtcp_xr.h
+++ b/pjmedia/include/pjmedia/rtcp_xr.h
@@ -392,7 +392,6 @@ PJ_DECL(pj_status_t) pjmedia_rtcp_xr_update_info(
  * @param session   RTCP XR session.
  * @param r_session RTCP session.
  * @param gmin      Gmin value (defined in RFC 3611), set to 0 for default (16).
- * @param ptime	    Packet time.
  * @param frames_per_packet
 		    Number of frames per packet.
  */
@@ -418,7 +417,7 @@ void pjmedia_rtcp_xr_fini( pjmedia_rtcp_xr_session *session );
  * @param size	    Size of the incoming packet.
  */
 void pjmedia_rtcp_xr_rx_rtcp_xr( pjmedia_rtcp_xr_session *session,
-				 const void *rtcp_xr_pkt,
+				 const void *rtcp_pkt,
 				 pj_size_t size);
 
 /**
diff --git a/pjmedia/include/pjmedia/sdp.h b/pjmedia/include/pjmedia/sdp.h
index c8eb902c..456a0476 100644
--- a/pjmedia/include/pjmedia/sdp.h
+++ b/pjmedia/include/pjmedia/sdp.h
@@ -522,6 +522,7 @@ PJ_DECL(pj_status_t) pjmedia_sdp_transport_cmp(const pj_str_t *t1,
 /**
  * Deactivate SDP media.
  *
+ * @param pool	    Memory pool to allocate memory from.
  * @param m	    The SDP media to deactivate.
  *
  * @return	    PJ_SUCCESS when SDP media successfully deactivated,
@@ -534,6 +535,7 @@ PJ_DECL(pj_status_t) pjmedia_sdp_media_deactivate(pj_pool_t *pool,
 /**
  * Clone SDP media description and deactivate the new SDP media.
  *
+ * @param pool	    Memory pool to allocate memory for the clone.
  * @param rhs	    The SDP media to clone.
  *
  * @return	    New media descrption with deactivated indication.
@@ -672,7 +674,7 @@ PJ_DECL(pj_status_t) pjmedia_sdp_session_cmp(const pjmedia_sdp_session *sd1,
  *
  * @return		PJ_SUCCESS or the appropriate error code.
  */
-PJ_DECL(pj_status_t) pjmedia_sdp_session_add_attr(pjmedia_sdp_session *m,
+PJ_DECL(pj_status_t) pjmedia_sdp_session_add_attr(pjmedia_sdp_session *s,
 						  pjmedia_sdp_attr *attr);
 
 
diff --git a/pjmedia/include/pjmedia/stereo.h b/pjmedia/include/pjmedia/stereo.h
index e3c93d28..3baf5597 100644
--- a/pjmedia/include/pjmedia/stereo.h
+++ b/pjmedia/include/pjmedia/stereo.h
@@ -148,17 +148,17 @@ PJ_INLINE(pj_status_t) pjmedia_convert_channel_1ton(pj_int16_t multi[],
 
 
 /** 
- * Options for channel converter port. The @pjmedia_stereo_options is also
+ * Options for channel converter port. The #pjmedia_stereo_options is also
  * valid for this port options.
  */
-enum pjmedia_stereo_port_options
+typedef enum pjmedia_stereo_port_options
 {
     /**
      * Specifies whether this port should not destroy downstream port when 
      * this port is destroyed.
      */
     PJMEDIA_STEREO_DONT_DESTROY_DN  = 4
-};
+} pjmedia_stereo_port_options;
 
 
 /**
diff --git a/pjmedia/include/pjmedia/stream.h b/pjmedia/include/pjmedia/stream.h
index c45201ec..c3454ac1 100644
--- a/pjmedia/include/pjmedia/stream.h
+++ b/pjmedia/include/pjmedia/stream.h
@@ -130,7 +130,7 @@ struct pjmedia_stream_info
 
 #if defined(PJMEDIA_STREAM_ENABLE_KA) && PJMEDIA_STREAM_ENABLE_KA!=0
     pj_bool_t		use_ka;	    /**< Stream keep-alive and NAT hole punch
-					 (see @ref PJMEDIA_STREAM_ENABLE_KA)
+					 (see #PJMEDIA_STREAM_ENABLE_KA)
 					 is enabled?			    */
 #endif
 };
diff --git a/pjmedia/include/pjmedia/transport_ice.h b/pjmedia/include/pjmedia/transport_ice.h
index 0e7816fc..2b3d857f 100644
--- a/pjmedia/include/pjmedia/transport_ice.h
+++ b/pjmedia/include/pjmedia/transport_ice.h
@@ -160,7 +160,7 @@ PJ_DECL(pj_status_t) pjmedia_ice_create(pjmedia_endpt *endpt,
 
 
 /**
- * The same as @pjmedia_ice_create with additional \a options param.
+ * The same as #pjmedia_ice_create() with additional \a options param.
  *
  * @param endpt		The media endpoint.
  * @param name		Optional name to identify this ICE media transport
diff --git a/pjmedia/include/pjmedia/types.h b/pjmedia/include/pjmedia/types.h
index a4c71743..c39a4243 100644
--- a/pjmedia/include/pjmedia/types.h
+++ b/pjmedia/include/pjmedia/types.h
@@ -458,7 +458,7 @@ pjmedia_frame_ext_get_subframe(const pjmedia_frame_ext *frm, unsigned n)
  *
  * @param frm		    The frame.
  * @param dst		    Destination buffer.
- * @param maxsize	    Maximum size to copy (i.e. the size of the
+ * @param maxlen	    Maximum size to copy (i.e. the size of the
  *			    destination buffer).
  *
  * @return		    Total size of payload copied.