Re #1134 (misc fixes): fixed various doxygen warnings, as well as added overview section in pjmedia documentation
git-svn-id: https://svn.pjsip.org/repos/pjproject/trunk@3327 74dad513-b988-da41-8d7b-12977e46ad98
diff --git a/pjlib/include/pj/config_site_sample.h b/pjlib/include/pj/config_site_sample.h
index 2751ab2..0c7832f 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 09c6209..ba28bc0 100644
--- a/pjmedia/include/pjmedia-audiodev/audiodev.h
+++ b/pjmedia/include/pjmedia-audiodev/audiodev.h
@@ -455,7 +455,7 @@
*
* @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 @@
*
* @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 8cc232e..e8df0a0 100644
--- a/pjmedia/include/pjmedia-codec/amr_helper.h
+++ b/pjmedia/include/pjmedia-codec/amr_helper.h
@@ -597,7 +597,7 @@
/**
- * 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 @@
* '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 @@
*
* @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 @@
* @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 e12f348..9934489 100644
--- a/pjmedia/include/pjmedia/conference.h
+++ b/pjmedia/include/pjmedia/conference.h
@@ -239,7 +239,7 @@
/**
* <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 70cff90..ec87c0f 100644
--- a/pjmedia/include/pjmedia/delaybuf.h
+++ b/pjmedia/include/pjmedia/delaybuf.h
@@ -79,7 +79,7 @@
* 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 261d761..a2b03f3 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 rather complete media stack, distributed under Open Source/GPL
- * terms, and featuring small footprint and good extensibility and portability.
+ * 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.
*
- * 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.
+ * @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.
*
- * Also please read the documentation about @ref PJMEDIA_PORT
- * which is a major concept that is used for implementing many objects in
- * the library.
+ * 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.
*
* \n
- * @section pjmedia_codec_sec PJMEDIA-CODEC
+ * @subsection org1 Organization
*
+ * At the top-most level, PJMEDIA library suite contains the following
+ * libraries.
+ *
+ * @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.
+ * 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 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.
- *
- *
- * \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 ccfff18..c460575 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 8ad2795..63f0aa5 100644
--- a/pjmedia/include/pjmedia/rtcp_xr.h
+++ b/pjmedia/include/pjmedia/rtcp_xr.h
@@ -392,7 +392,6 @@
* @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 @@
* @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 c8eb902..456a047 100644
--- a/pjmedia/include/pjmedia/sdp.h
+++ b/pjmedia/include/pjmedia/sdp.h
@@ -522,6 +522,7 @@
/**
* 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 @@
/**
* 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 @@
*
* @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 e3c93d2..3baf559 100644
--- a/pjmedia/include/pjmedia/stereo.h
+++ b/pjmedia/include/pjmedia/stereo.h
@@ -148,17 +148,17 @@
/**
- * 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 c45201e..c3454ac 100644
--- a/pjmedia/include/pjmedia/stream.h
+++ b/pjmedia/include/pjmedia/stream.h
@@ -130,7 +130,7 @@
#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 0e7816f..2b3d857 100644
--- a/pjmedia/include/pjmedia/transport_ice.h
+++ b/pjmedia/include/pjmedia/transport_ice.h
@@ -160,7 +160,7 @@
/**
- * 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 a4c7174..c39a424 100644
--- a/pjmedia/include/pjmedia/types.h
+++ b/pjmedia/include/pjmedia/types.h
@@ -458,7 +458,7 @@
*
* @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.