Added documentation for the rtsp plugin. Fixes #345393.

Original commit message from CVS:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-good-plugins-docs.sgml:
* docs/plugins/gst-plugins-good-plugins-sections.txt:
* gst/rtsp/gstrtpdec.c: (gst_rtpdec_class_init):
* gst/rtsp/gstrtspsrc.c:
* gst/rtsp/gstrtspsrc.h:
Added documentation for the rtsp plugin. Fixes #345393.

ChangeLog

@@ -1,3 +1,13 @@
+2006-06-20  Wim Taymans  <wim@fluendo.com>
+
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-good-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-good-plugins-sections.txt:
+	* gst/rtsp/gstrtpdec.c: (gst_rtpdec_class_init):
+	* gst/rtsp/gstrtspsrc.c:
+	* gst/rtsp/gstrtspsrc.h:
+	Added documentation for the rtsp plugin. Fixes #345393.
+
 2006-06-20  Wim Taymans  <wim@fluendo.com>
 
 	* gst/rtsp/rtspconnection.c: (inet_aton), (rtsp_connection_send),

docs/plugins/Makefile.am

@@ -82,6 +82,8 @@ EXTRA_HFILES = \
 	$(top_srcdir)/gst/level/gstlevel.h \
 	$(top_srcdir)/gst/goom/gstgoom.h \
 	$(top_srcdir)/gst/id3demux/gstid3demux.h \
+	$(top_srcdir)/gst/rtsp/gstrtpdec.h \
+	$(top_srcdir)/gst/rtsp/gstrtspsrc.h \
 	$(top_srcdir)/gst/wavparse/gstwavparse.h \
 	$(top_srcdir)/ext/cairo/gsttimeoverlay.h \
 	$(top_srcdir)/ext/cdio/gstcdiocddasrc.h \

docs/plugins/gst-plugins-good-plugins-docs.sgml

@@ -35,6 +35,8 @@
     <xi:include href="xml/element-multiudpsink.xml" />
     <xi:include href="xml/element-multipartmux.xml" />
     <xi:include href="xml/element-multipartdemux.xml" />
+    <xi:include href="xml/element-rtspsrc.xml" />
+    <xi:include href="xml/element-rtpdec.xml" />
     <xi:include href="xml/element-smokedec.xml" />
     <xi:include href="xml/element-smokeenc.xml" />
     <xi:include href="xml/element-videobalance.xml" />

docs/plugins/gst-plugins-good-plugins-sections.txt

@@ -156,6 +156,37 @@ GST_JPEGENC_CLASS
 GST_IS_JPEGENC_CLASS
 </SECTION>
 
+<SECTION>
+<FILE>element-rtspsrc</FILE>
+GstRTSPProto
+GstRTSPSrc
+<TITLE>rtspsrc</TITLE>
+<SUBSECTION Standard>
+GstRTSPStream
+GstRTSPSrcClass
+GST_RTSPSRC
+GST_IS_RTSPSRC
+GST_TYPE_RTSPSRC
+gst_rtspsrc_get_type
+GST_RTSPSRC_CLASS
+GST_IS_RTSPSRC_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpdec</FILE>
+GstRTPDec
+<TITLE>rtpdec</TITLE>
+<SUBSECTION Standard>
+gst_rtpdec_plugin_init
+GstRTPDecClass
+GST_RTPDEC
+GST_IS_RTPDEC
+GST_TYPE_RTPDEC
+gst_rtpdec_get_type
+GST_RTPDEC_CLASS
+GST_IS_RTPDEC_CLASS
+</SECTION>
+
 <SECTION>
 <FILE>element-smokedec</FILE>
 GstSmokeDec

gst/rtsp/gstrtpdec.c

@@ -18,6 +18,19 @@
  */
 /* Element-Checklist-Version: 5 */
 
+/**
+ * SECTION:element-rtpdec
+ *
+ * <refsect2>
+ * <para>
+ * A simple RTP session manager used internally by rtspsrc.
+ * </para>
+ * </refsect2>
+ *
+ * Last reviewed on 2006-06-20 (0.10.4)
+ */
+
+
 #include "gstrtpdec.h"
 
 GST_DEBUG_CATEGORY (rtpdec_debug);
@@ -138,7 +151,10 @@ gst_rtpdec_class_init (gpointer g_class)
   gobject_class->set_property = gst_rtpdec_set_property;
   gobject_class->get_property = gst_rtpdec_get_property;
 
-  g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_SKIP, g_param_spec_int ("skip", "skip", "skip", G_MININT, G_MAXINT, 0, G_PARAM_READWRITE));      /* CHECKME */
+  /* FIXME, this is unused and probably copied from somewhere */
+  g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_SKIP,
+      g_param_spec_int ("skip", "Skip", "skip (unused)", G_MININT, G_MAXINT, 0,
+          G_PARAM_READWRITE));
 
   parent_class = g_type_class_peek_parent (klass);
 

gst/rtsp/gstrtspsrc.c

@@ -16,6 +16,49 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION:element-rtspsrc
+ *
+ * <refsect2>
+ * <para>
+ * Makes a connection to an RTSP server and read the data.
+ * rtspsrc strictly follows RFC 2326 and therefore does not (yet) support
+ * RealMedia/Quicktime/Microsoft extensions.
+ * </para>
+ * <para>
+ * RTSP supports transport over TCP or UDP in unicast or multicast mode. By
+ * default rtspsrc will negotiate a connection in the following order:
+ * UDP unicast/UDP multicast/TCP. The order cannot be changed but the allowed
+ * protocols can be controlled with the "protocols" property.
+ * </para>
+ * <para>
+ * rtspsrc currently understands SDP as the format of the session description.
+ * For each stream listed in the SDP a new rtp_stream%d pad will be created
+ * with caps derived from the SDP media description. This is a caps of mime type
+ * "application/x-rtp" that can be connected to any available rtp depayloader
+ * element. 
+ * </para>
+ * <para>
+ * rtspsrc will internally instantiate an RTP session manager element
+ * that will handle the RTCP messages to and from the server, jitter removal,
+ * packet reordering along with providing a clock for the pipeline. 
+ * This feature is however currently not yet implemented.
+ * </para>
+ * <para>
+ * rtspsrc acts like a live source and will therefore only generate data in the 
+ * PLAYING state.
+ * </para>
+ * <title>Example launch line</title>
+ * <para>
+ * <programlisting>
+ * gst-launch rtspsrc location=rtsp://some.server/url ! fakesink
+ * </programlisting>
+ * Establish a connection to an RTSP server and send the stream to a fakesink.
+ * </para>
+ * </refsect2>
+ *
+ * Last reviewed on 2006-06-20 (0.10.4)
+ */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

gst/rtsp/gstrtspsrc.h

@@ -23,9 +23,7 @@
 
 #include <gst/gst.h>
 
-#ifdef __cplusplus
+G_BEGIN_DECLS
-extern "C" {
-#endif /* __cplusplus */
 
 #include "gstrtsp.h"
 #include "rtsp.h"
@@ -103,10 +101,6 @@ struct _GstRTSPSrcClass {
 
 GType gst_rtspsrc_get_type(void);
 
-
+G_END_DECLS
-#ifdef __cplusplus
-}
-#endif /* __cplusplus */
-
 
 #endif /* __GST_RTSPSRC_H__ */