ext/gio/: Make the documentation of giosink/giosrc complete, large parts are based...

Original commit message from CVS:
* ext/gio/gstgiosink.c:
* ext/gio/gstgiosrc.c:
Make the documentation of giosink/giosrc complete, large parts
are based on the gnomevfssink/gnomevfssrc docs.

diff --git a/ChangeLog b/ChangeLog
index 5bd78c0..17541ba 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2008-02-12  Sebastian Dröge  <slomo@circular-chaos.org>
 
+       * ext/gio/gstgiosink.c:
+       * ext/gio/gstgiosrc.c:
+       Make the documentation of giosink/giosrc complete, large parts
+       are based on the gnomevfssink/gnomevfssrc docs.
+
+2008-02-12  Sebastian Dröge  <slomo@circular-chaos.org>
+
        * docs/plugins/gst-plugins-base-plugins-docs.sgml:
        * docs/plugins/gst-plugins-base-plugins-sections.txt:
        * docs/plugins/gst-plugins-base-plugins.args:

diff --git a/ext/gio/gstgiosink.c b/ext/gio/gstgiosink.c
index a01e6fd..894c795 100644 (file)
--- a/ext/gio/gstgiosink.c
+++ b/ext/gio/gstgiosink.c
@@ -21,13 +21,39 @@
 
 /**
  * SECTION:element-giosink
+ * @short_description: Write a stream to any GIO-supported location
+ * @see_also: #GstFileSink, #GstGnomeVFSSink, #GstGioSrc
  *
  * <refsect2>
- * <title>Example launch line</title>
  * <para>
+ * This plugin writes incoming data to a local or remote location specified
+ * by an URI. This location can be specified using any protocol supported by
+ * the GIO library or it's VFS backends. Common protocols are 'file', 'ftp',
+ * or 'smb'.
+ * </para>
+ * <para>
+ * Example pipeline:
+ * <programlisting>
+ * gst-launch -v filesrc location=input.xyz ! giosink location=file:///home/joe/out.xyz
+ * </programlisting>
+ * The above pipeline will simply copy a local file. Instead of giosink,
+ * we could just as well have used the filesink element here.
+ * </para>
+ * <para>
+ * Another example pipeline:
+ * <programlisting>
+ * gst-launch -v filesrc location=foo.mp3 ! mad ! flacenc ! giosink location=smb://othercomputer/foo.flac
+ * </programlisting>
+ * The above pipeline will re-encode an mp3 file into FLAC format and store
+ * it on a remote host using the Samba protocol.
+ * </para>
+ * <para>
+ * Another example pipeline:
  * <programlisting>
- * gst-launch audiotestsrc num-buffers=100 ! flacenc ! giosink location=file:///home/foo/bar.flac
+ * gst-launch -v audiotestsrc num-buffers=100 ! vorbisenc ! oggmux ! giosink location=file:///home/foo/bar.ogg
  * </programlisting>
+ * The above pipeline will encode a 440Hz sine wave to Ogg Vorbis and stores
+ * it in the home directory of user foo.
  * </para>
  * </refsect2>
  */

diff --git a/ext/gio/gstgiosrc.c b/ext/gio/gstgiosrc.c
index ee336f0..cfa4da9 100644 (file)
--- a/ext/gio/gstgiosrc.c
+++ b/ext/gio/gstgiosrc.c
@@ -21,13 +21,40 @@
 
 /**
  * SECTION:element-giosrc
+ * @short_description: Read from any GIO-supported location
+ * @see_also: #GstFileSrc, #GstGnomeVFSSrc, #GstGioSink
  *
  * <refsect2>
- * <title>Example launch line</title>
  * <para>
+ * This plugin reads data from a local or remote location specified
+ * by an URI. This location can be specified using any protocol supported by
+ * the GIO library or it's VFS backends. Common protocols are 'file', 'http',
+ * 'ftp', or 'smb'.
+ * </para>
+ * <para>
+ * Example pipeline:
+ * <programlisting>
+ * gst-launch -v giosrc location=file:///home/joe/foo.xyz ! fakesink
+ * </programlisting>
+ * The above pipeline will simply read a local file and do nothing with the
+ * data read. Instead of giosrc, we could just as well have used the
+ * filesrc element here.
+ * </para>
+ * <para>
+ * Another example pipeline:
+ * <programlisting>
+ * gst-launch -v giosrc location=smb://othercomputer/foo.xyz ! filesink location=/home/joe/foo.xyz
+ * </programlisting>
+ * The above pipeline will copy a file from a remote host to the local file
+ * system using the Samba protocol.
+ * </para>
+ * <para>
+ * Yet another example pipeline:
  * <programlisting>
- * gst-launch giosrc location=file:///home/foo/bar.ext ! fakesink
+ * gst-launch -v giosrc location=http://music.foobar.com/demo.mp3 ! mad ! audioconvert ! audioresample ! alsasink
  * </programlisting>
+ * The above pipeline will read and decode and play an mp3 file from a
+ * web server using the http protocol.
  * </para>
  * </refsect2>
  */