gst/: More doc updates. More xrefs.

Original commit message from CVS:
* gst/deinterlace/gstdeinterlace.c:
* gst/rtpmanager/gstrtpbin.c:
* gst/rtpmanager/gstrtpclient.c:
* gst/rtpmanager/gstrtpjitterbuffer.c:
* gst/rtpmanager/gstrtpptdemux.c:
* gst/rtpmanager/gstrtpsession.c:
* gst/rtpmanager/gstrtpssrcdemux.c:
* gst/sdp/gstsdpdemux.c:
More doc updates. More xrefs.

gst/rtpmanager/gstrtpbin.c

@@ -21,61 +21,50 @@
  * SECTION:element-gstrtpbin
  * @see_also: gstrtpjitterbuffer, gstrtpsession, gstrtpptdemux, gstrtpssrcdemux
  *
- * <refsect2>
+ * RTP bin combines the functions of #GstRtpSession, #GstRtpsSrcDemux,
- * <para>
+ * #GstRtpJitterBuffer and #GstRtpPtDemux in one element. It allows for multiple
- * RTP bin combines the functions of gstrtpsession, gstrtpssrcdemux, gstrtpjitterbuffer
+ * RTP sessions that will be synchronized together using RTCP SR packets.
- * and gstrtpptdemux in one element. It allows for multiple RTP sessions that will
+ * 
- * be synchronized together using RTCP SR packets.
+ * #GstRtpBin is configured with a number of request pads that define the
- * </para>
+ * functionality that is activated, similar to the #GstRtpSession element.
- * <para>
+ * 
- * gstrtpbin is configured with a number of request pads that define the
+ * To use #GstRtpBin as an RTP receiver, request a recv_rtp_sink_%%d pad. The session
- * functionality that is activated, similar to the gstrtpsession element.
- * </para>
- * <para>
- * To use gstrtpbin as an RTP receiver, request a recv_rtp_sink_%%d pad. The session
  * number must be specified in the pad name. 
  * Data received on the recv_rtp_sink_%%d pad will be processed in the gstrtpsession
- * manager and after being validated forwarded on gstrtpssrcdemuxer element. Each
+ * manager and after being validated forwarded on #GstRtpsSrcDemux element. Each
- * RTP stream is demuxed based on the SSRC and send to a gstrtpjitterbuffer. After
+ * RTP stream is demuxed based on the SSRC and send to a #GstRtpJitterBuffer. After
  * the packets are released from the jitterbuffer, they will be forwarded to a
- * gstrtpptdemuxer element. The gstrtpptdemuxer element will demux the packets based
+ * #GstRtpsSrcDemux element. The #GstRtpsSrcDemux element will demux the packets based
  * on the payload type and will create a unique pad recv_rtp_src_%%d_%%d_%%d on
  * gstrtpbin with the session number, SSRC and payload type respectively as the pad
  * name.
- * </para>
+ * 
- * <para>
+ * To also use #GstRtpBin as an RTCP receiver, request a recv_rtcp_sink_%%d pad. The
- * To also use gstrtpbin as an RTCP receiver, request a recv_rtcp_sink_%%d pad. The
  * session number must be specified in the pad name.
- * </para>
+ * 
- * <para>
  * If you want the session manager to generate and send RTCP packets, request
  * the send_rtcp_src_%%d pad with the session number in the pad name. Packet pushed
  * on this pad contain SR/RR RTCP reports that should be sent to all participants
  * in the session.
- * </para>
+ * 
- * <para>
+ * To use #GstRtpBin as a sender, request a send_rtp_sink_%%d pad, which will
- * To use gstrtpbin as a sender, request a send_rtp_sink_%%d pad, which will
  * automatically create a send_rtp_src_%%d pad. If the session number is not provided,
  * the pad from the lowest available session will be returned. The session manager will modify the
  * SSRC in the RTP packets to its own SSRC and wil forward the packets on the
  * send_rtp_src_%%d pad after updating its internal state.
- * </para>
+ * 
- * <para>
  * The session manager needs the clock-rate of the payload types it is handling
- * and will signal the GstRtpSession::request-pt-map signal when it needs such a
+ * and will signal the #GstRtpSession::request-pt-map signal when it needs such a
- * mapping. One can clear the cached values with the GstRtpSession::clear-pt-map
+ * mapping. One can clear the cached values with the #GstRtpSession::clear-pt-map
  * signal.
- * </para>
+ * 
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
+ * |[
- * <programlisting>
  * gst-launch udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink_0 \
  *     gstrtpbin ! rtptheoradepay ! theoradec ! xvimagesink
- * </programlisting>
+ * ]| Receive RTP data from port 5000 and send to the session 0 in gstrtpbin.
- * Receive RTP data from port 5000 and send to the session 0 in gstrtpbin.
+ * |[
- * </para>
- * <para>
- * <programlisting>
  * gst-launch gstrtpbin name=rtpbin \
  *         v4l2src ! ffmpegcolorspace ! ffenc_h263 ! rtph263ppay ! rtpbin.send_rtp_sink_0 \
  *                   rtpbin.send_rtp_src_0 ! udpsink port=5000                            \
@@ -85,8 +74,7 @@
  *                   rtpbin.send_rtp_src_1 ! udpsink port=5002                            \
  *                   rtpbin.send_rtcp_src_1 ! udpsink port=5003 sync=false async=false    \
  *                   udpsrc port=5007 ! rtpbin.recv_rtcp_sink_1
- * </programlisting>
+ * ]| Encode and payload H263 video captured from a v4l2src. Encode and payload AMR
- * Encode and payload H263 video captured from a v4l2src. Encode and payload AMR
  * audio generated from audiotestsrc. The video is sent to session 0 in rtpbin
  * and the audio is sent to session 1. Video packets are sent on UDP port 5000
  * and audio packets on port 5002. The video RTCP packets for session 0 are sent
@@ -95,9 +83,7 @@
  * is received on port 5007. Since RTCP packets from the sender should be sent
  * as soon as possible and do not participate in preroll, sync=false and 
  * async=false is configured on udpsink
- * </para>
+ * |[
- * <para>
- * <programlisting>
  * gst-launch -v gstrtpbin name=rtpbin                                          \
  *     udpsrc caps="application/x-rtp,media=(string)video,clock-rate=(int)90000,encoding-name=(string)H263-1998" \
  *             port=5000 ! rtpbin.recv_rtp_sink_0                                \
@@ -109,8 +95,7 @@
  *         rtpbin. ! rtpamrdepay ! amrnbdec ! alsasink                           \
  *      udpsrc port=5003 ! rtpbin.recv_rtcp_sink_1                               \
  *      rtpbin.send_rtcp_src_1 ! udpsink port=5007 sync=false async=false
- * </programlisting>
+ * ]| Receive H263 on port 5000, send it through rtpbin in session 0, depayload,
- * Receive H263 on port 5000, send it through rtpbin in session 0, depayload,
  * decode and display the video.
  * Receive AMR on port 5002, send it through rtpbin in session 1, depayload,
  * decode and play the audio.
@@ -119,7 +104,6 @@
  * synchronisation.
  * Send RTCP reports for session 0 on port 5005 and RTCP reports for session 1
  * on port 5007.
- * </para>
  * </refsect2>
  *
  * Last reviewed on 2007-08-30 (0.10.6)
@@ -1200,7 +1184,7 @@ gst_rtp_bin_class_init (GstRtpBinClass * klass)
    * @rtpbin: the object which received the signal
    *
    * Clear all previously cached pt-mapping obtained with
-   * GstRtpBin::request-pt-map.
+   * #GstRtpBin::request-pt-map.
    */
   gst_rtp_bin_signals[SIGNAL_CLEAR_PT_MAP] =
       g_signal_new ("clear-pt-map", G_TYPE_FROM_CLASS (klass),

gst/rtpmanager/gstrtpclient.c

@@ -21,20 +21,17 @@
  * SECTION:element-gstrtpclient
  * @see_also: gstrtpjitterbuffer, gstrtpbin, gstrtpsession
  *
- * <refsect2>
- * <para>
  * This element handles RTP data from one client. It accepts multiple RTP streams that
  * should be synchronized together.
- * </para>
+ * 
- * <para>
  * Normally the SSRCs that map to the same CNAME (as given in the RTCP SDES messages)
  * should be synchronized.
- * </para>
+ * 
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
+ * |[
- * <programlisting>
+ * FIXME: gst-launch
- * </programlisting>
+ * ]| FIXME: describe
- * </para>
  * </refsect2>
  *
  * Last reviewed on 2007-04-02 (0.10.5)

gst/rtpmanager/gstrtpjitterbuffer.c

@@ -26,34 +26,28 @@
 /**
  * SECTION:element-gstrtpjitterbuffer
  *
- * <refsect2>
- * <para>
  * This element reorders and removes duplicate RTP packets as they are received
  * from a network source. It will also wait for missing packets up to a
- * configurable time limit using the ::latency property. Packets arriving too
+ * configurable time limit using the #GstRtpJitterBuffer:latency property.
- * late are considered to be lost packets.
+ * Packets arriving too late are considered to be lost packets.
- * </para>
+ * 
- * <para>
+ * This element acts as a live element and so adds #GstRtpJitterBuffer:latency
- * This element acts as a live element and so adds ::latency to the pipeline.
+ * to the pipeline.
- * </para>
+ * 
- * <para>
  * The element needs the clock-rate of the RTP payload in order to estimate the
  * delay. This information is obtained either from the caps on the sink pad or,
- * when no caps are present, from the ::request-pt-map signal. To clear the
+ * when no caps are present, from the #GstRtpJitterBuffer::request-pt-map signal.
- * previous pt-map use the ::clear-pt-map signal.
+ * To clear the previous pt-map use the #GstRtpJitterBuffer::clear-pt-map signal.
- * </para>
+ * 
- * <para>
  * This element will automatically be used inside gstrtpbin.
- * </para>
+ * 
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
+ * |[
- * <programlisting>
  * gst-launch rtspsrc location=rtsp://192.168.1.133:8554/mpeg1or2AudioVideoTest ! gstrtpjitterbuffer ! rtpmpvdepay ! mpeg2dec ! xvimagesink
- * </programlisting>
+ * ]| Connect to a streaming server and decode the MPEG video. The jitterbuffer is
- * Connect to a streaming server and decode the MPEG video. The jitterbuffer is
  * inserted into the pipeline to smooth out network jitter and to reorder the
  * out-of-order RTP packets.
- * </para>
  * </refsect2>
  *
  * Last reviewed on 2007-05-28 (0.10.5)

gst/rtpmanager/gstrtpptdemux.c

@@ -26,29 +26,25 @@
 /**
  * SECTION:element-gstrtpptdemux
  *
- * <refsect2>
+ * gstrtpptdemux acts as a demuxer for RTP packets based on the payload type of
- * <para>
+ * the packets. Its main purpose is to allow an application to easily receive
- * gstrtpptdemux acts as a demuxer for RTP packets based on the payload type of the
+ * and decode an RTP stream with multiple payload types.
- * packets. Its main purpose is to allow an application to easily receive and
+ * 
- * decode an RTP stream with multiple payload types.
- * </para>
- * <para>
  * For each payload type that is detected, a new pad will be created and the
- * ::new-payload-type signal will be emitted. When the payload for the RTP
+ * #GstRtpPtDemux::new-payload-type signal will be emitted. When the payload for
- * stream changes, the ::payload-type-change signal will be emitted.
+ * the RTP stream changes, the #GstRtpPtDemux::payload-type-change signal will be
- * </para>
+ * emitted.
- * <para>
+ * 
  * The element will try to set complete and unique application/x-rtp caps on the
- * outgoing buffers and pads based on the result of the ::request-pt-map signal.
+ * outgoing buffers and pads based on the result of the
- * </para>
+ * #GstRtpPtDemux::request-pt-map signal.
+ * 
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
+ * |[
- * <programlisting>
  * gst-launch udpsrc caps="application/x-rtp" ! gstrtpptdemux ! fakesink
- * </programlisting>
+ * ]| Takes an RTP stream and send the RTP packets with the first detected
- * Takes an RTP stream and send the RTP packets with the first detected payload
+ * payload type to fakesink, discarding the other payload types.
- * type to fakesink, discarding the other payload types.
- * </para>
  * </refsect2>
  *
  * Last reviewed on 2007-05-28 (0.10.5)

gst/rtpmanager/gstrtpsession.c

@@ -21,14 +21,11 @@
  * SECTION:element-gstrtpsession
  * @see_also: gstrtpjitterbuffer, gstrtpbin, gstrtpptdemux, gstrtpssrcdemux
  *
- * <refsect2>
- * <para>
  * The RTP session manager models one participant with a unique SSRC in an RTP
  * session. This session can be used to send and receive RTP and RTCP packets.
  * Based on what REQUEST pads are requested from the session manager, specific
  * functionality can be activated.
- * </para>
+ * 
- * <para>
  * The session manager currently implements RFC 3550 including:
  * <itemizedlist>
  *   <listitem>
@@ -44,84 +41,68 @@
  *     <para>Scheduling of RR/SR RTCP packets.</para>
  *   </listitem>
  * </itemizedlist>
- * </para>
+ * 
- * <para>
  * The gstrtpsession will not demux packets based on SSRC or payload type, nor will
- * it correct for packet reordering and jitter. Use gstrtpssrcdemux, gstrtpptdemux and
+ * it correct for packet reordering and jitter. Use #GstRtpsSrcDemux,
- * gstrtpjitterbuffer in addition to gstrtpsession to perform these tasks. It is
+ * #GstRtpPtDemux and GstRtpJitterBuffer in addition to #GstRtpSession to
- * usually a good idea to use gstrtpbin, which combines all these features in one
+ * perform these tasks. It is usually a good idea to use #GstRtpBin, which
- * element.
+ * combines all these features in one element.
- * </para>
+ * 
- * <para>
+ * To use #GstRtpSession as an RTP receiver, request a recv_rtp_sink pad, which will
- * To use gstrtpsession as an RTP receiver, request a recv_rtp_sink pad, which will
  * automatically create recv_rtp_src pad. Data received on the recv_rtp_sink pad
  * will be processed in the session and after being validated forwarded on the
  * recv_rtp_src pad.
- * </para>
+ * 
- * <para>
+ * To also use #GstRtpSession as an RTCP receiver, request a recv_rtcp_sink pad,
- * To also use gstrtpsession as an RTCP receiver, request a recv_rtcp_sink pad,
  * which will automatically create a sync_src pad. Packets received on the RTCP
  * pad will be used by the session manager to update the stats and database of
  * the other participants. SR packets will be forwarded on the sync_src pad
  * so that they can be used to perform inter-stream synchronisation when needed.
- * </para>
+ * 
- * <para>
  * If you want the session manager to generate and send RTCP packets, request
  * the send_rtcp_src pad. Packet pushed on this pad contain SR/RR RTCP reports
  * that should be sent to all participants in the session.
- * </para>
+ * 
- * <para>
+ * To use #GstRtpSession as a sender, request a send_rtp_sink pad, which will
- * To use gstrtpsession as a sender, request a send_rtp_sink pad, which will
  * automatically create a send_rtp_src pad. The session manager will modify the
  * SSRC in the RTP packets to its own SSRC and wil forward the packets on the
  * send_rtp_src pad after updating its internal state.
- * </para>
+ * 
- * <para>
  * The session manager needs the clock-rate of the payload types it is handling
- * and will signal the GstRtpSession::request-pt-map signal when it needs such a
+ * and will signal the #GstRtpSession::request-pt-map signal when it needs such a
- * mapping. One can clear the cached values with the GstRtpSession::clear-pt-map
+ * mapping. One can clear the cached values with the #GstRtpSession::clear-pt-map
  * signal.
- * </para>
+ * 
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
+ * |[
- * <programlisting>
  * gst-launch udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink gstrtpsession .recv_rtp_src ! rtptheoradepay ! theoradec ! xvimagesink
- * </programlisting>
+ * ]| Receive theora RTP packets from port 5000 and send them to the depayloader,
- * Receive theora RTP packets from port 5000 and send them to the depayloader,
  * decoder and display. Note that the application/x-rtp caps on udpsrc should be
  * configured based on some negotiation process such as RTSP for this pipeline
  * to work correctly.
- * </para>
+ * |[
- * <para>
- * <programlisting>
  * gst-launch udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink gstrtpsession name=session \
  *        .recv_rtp_src ! rtptheoradepay ! theoradec ! xvimagesink \
  *     udpsrc port=5001 caps="application/x-rtcp" ! session.recv_rtcp_sink
- * </programlisting>
+ * ]| Receive theora RTP packets from port 5000 and send them to the depayloader,
- * Receive theora RTP packets from port 5000 and send them to the depayloader,
  * decoder and display. Receive RTCP packets from port 5001 and process them in
  * the session manager.
  * Note that the application/x-rtp caps on udpsrc should be
  * configured based on some negotiation process such as RTSP for this pipeline
  * to work correctly.
- * </para>
+ * |[
- * <para>
- * <programlisting>
  * gst-launch videotestsrc ! theoraenc ! rtptheorapay ! .send_rtp_sink gstrtpsession .send_rtp_src ! udpsink port=5000
- * </programlisting>
+ * ]| Send theora RTP packets through the session manager and out on UDP port
- * Send theora RTP packets through the session manager and out on UDP port 5000.
+ * 5000.
- * </para>
+ * |[
- * <para>
- * <programlisting>
  * gst-launch videotestsrc ! theoraenc ! rtptheorapay ! .send_rtp_sink gstrtpsession name=session .send_rtp_src \
  *     ! udpsink port=5000  session.send_rtcp_src ! udpsink port=5001
- * </programlisting>
+ * ]| Send theora RTP packets through the session manager and out on UDP port
- * Send theora RTP packets through the session manager and out on UDP port 5000.
+ * 5000. Send RTCP packets on port 5001. Note that this pipeline will not preroll
- * Send RTCP packets on port 5001. Note that this pipeline will not preroll
  * correctly because the second udpsink will not preroll correctly (no RTCP
  * packets are sent in the PAUSED state). Applications should manually set and
- * keep (see #gst_element_set_locked_state()) the RTCP udpsink to the PLAYING state.
+ * keep (see gst_element_set_locked_state()) the RTCP udpsink to the PLAYING state.
- * </para>
  * </refsect2>
  *
  * Last reviewed on 2007-05-28 (0.10.5)
@@ -492,7 +473,7 @@ gst_rtp_session_class_init (GstRtpSessionClass * klass)
    * GstRtpSession::clear-pt-map:
    * @sess: the object which received the signal
    *
-   * Clear the cached pt-maps requested with GstRtpSession::request-pt-map.
+   * Clear the cached pt-maps requested with #GstRtpSession::request-pt-map.
    */
   gst_rtp_session_signals[SIGNAL_CLEAR_PT_MAP] =
       g_signal_new ("clear-pt-map", G_TYPE_FROM_CLASS (klass),

gst/rtpmanager/gstrtpssrcdemux.c

@@ -22,24 +22,19 @@
 /**
  * SECTION:element-gstrtpssrcdemux
  *
- * <refsect2>
- * <para>
  * gstrtpssrcdemux acts as a demuxer for RTP packets based on the SSRC of the
  * packets. Its main purpose is to allow an application to easily receive and
  * decode an RTP stream with multiple SSRCs.
- * </para>
+ * 
- * <para>
  * For each SSRC that is detected, a new pad will be created and the
- * ::new-ssrc-pad signal will be emitted. 
+ * #GstRtpSsrcDemux::new-ssrc-pad signal will be emitted. 
- * </para>
+ * 
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
+ * |[
- * <programlisting>
  * gst-launch udpsrc caps="application/x-rtp" ! gstrtpssrcdemux ! fakesink
- * </programlisting>
+ * ]| Takes an RTP stream and send the RTP packets with the first detected SSRC
- * Takes an RTP stream and send the RTP packets with the first detected SSRC
  * to fakesink, discarding the other SSRCs.
- * </para>
  * </refsect2>
  *
  * Last reviewed on 2007-05-28 (0.10.5)
@@ -133,7 +128,7 @@ static gboolean gst_rtp_ssrc_demux_src_query (GstPad * pad, GstQuery * query);
 
 static guint gst_rtp_ssrc_demux_signals[LAST_SIGNAL] = { 0 };
 
-/**
+/*
  * Item for storing GstPad <-> SSRC pairs.
  */
 struct _GstRtpSsrcDemuxPad