diff options
author | Benny Prijono <bennylp@teluu.com> | 2010-09-30 04:23:27 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2010-09-30 04:23:27 +0000 |
commit | d6b77c8c0f20436dcbfc9db85da2e7d7d85fe4ef (patch) | |
tree | d3ca4822de8cd3426bb3644f4756c8900b37f57a /pjmedia/include | |
parent | 513fb792c867d3791fbd258151ab32c66c6c6249 (diff) |
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
Diffstat (limited to 'pjmedia/include')
-rw-r--r-- | pjmedia/include/pjmedia-audiodev/audiodev.h | 4 | ||||
-rw-r--r-- | pjmedia/include/pjmedia-codec/amr_helper.h | 9 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/conference.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/delaybuf.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/doxygen.h | 128 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/port.h | 36 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/rtcp_xr.h | 3 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/sdp.h | 4 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/stereo.h | 6 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/stream.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/transport_ice.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/types.h | 2 |
12 files changed, 141 insertions, 59 deletions
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. |