From 6ee61e4cb3d2c38665e051a52c833f1a8a766948 Mon Sep 17 00:00:00 2001
From: Stefan Kost <ensonic@users.sf.net>
Date: Mon, 16 Aug 2010 18:01:27 +0300
Subject: [PATCH] plugins: add example launch lines and more explanation to the
 docs.

The plugins where almost undocumented :/ ...
---
 plugins/elements/gstcapsfilter.c |  7 +++++++
 plugins/elements/gstfakesink.c   |  7 +++++++
 plugins/elements/gstfilesink.c   |  7 +++++++
 plugins/elements/gstfilesrc.c    |  7 +++++++
 plugins/elements/gsttee.c        | 17 ++++++++++++++++-
 5 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/plugins/elements/gstcapsfilter.c b/plugins/elements/gstcapsfilter.c
index 792337d..a144611 100644
--- a/plugins/elements/gstcapsfilter.c
+++ b/plugins/elements/gstcapsfilter.c
@@ -24,6 +24,13 @@
  *
  * The element does not modify data as such, but can enforce limitations on the
  * data format.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch videotestsrc ! video/x-raw-gray ! ffmpegcolorspace ! autovideosink
+ * ]| Limits acceptable video from videotestsrc to be grayscale.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/plugins/elements/gstfakesink.c b/plugins/elements/gstfakesink.c
index 1691908..ebae1f8 100644
--- a/plugins/elements/gstfakesink.c
+++ b/plugins/elements/gstfakesink.c
@@ -24,6 +24,13 @@
  * @see_also: #GstFakeSrc
  *
  * Dummy sink that swallows everything.
+ * 
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch audiotestsrc num-buffers=1000 ! fakesink sync=false
+ * ]| Render 1000 audio buffers (of default size) as fast as possible.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/plugins/elements/gstfilesink.c b/plugins/elements/gstfilesink.c
index 1c69f57..bcd514f 100644
--- a/plugins/elements/gstfilesink.c
+++ b/plugins/elements/gstfilesink.c
@@ -25,6 +25,13 @@
  * @see_also: #GstFileSrc
  *
  * Write incoming data to a file in the local file system.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch v4l2src num-buffers=1 ! jpegenc ! filesink location=capture1.jpeg
+ * ]| Capture one frame from a v4l2 camera and save as jpeg image.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/plugins/elements/gstfilesrc.c b/plugins/elements/gstfilesrc.c
index 81c2df8..0894de6 100644
--- a/plugins/elements/gstfilesrc.c
+++ b/plugins/elements/gstfilesrc.c
@@ -24,6 +24,13 @@
  * @see_also: #GstFileSrc
  *
  * Read data from a file in the local file system.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch filesrc location=song.ogg ! decodebin2 ! autoaudiosink
+ * ]| Play a song.ogg from local dir.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/plugins/elements/gsttee.c b/plugins/elements/gsttee.c
index a639b04..4f3cc07 100644
--- a/plugins/elements/gsttee.c
+++ b/plugins/elements/gsttee.c
@@ -25,7 +25,22 @@
  * SECTION:element-tee
  * @see_also: #GstIdentity
  *
- * Split data to multiple pads.
+ * Split data to multiple pads. Branching the data flow is useful when e.g.
+ * capturing a video where the video is shown on the screen and also encoded and
+ * written to a file. Another example is playing music and hooking up a
+ * visualisation module.
+ *
+ * One needs to use separate queue elements (or a multiqueue) in each branch to
+ * provide separate threads for each branch. Otherwise a blocked dataflow in one
+ * branch would stall the other branches.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch filesrc location=song.ogg ! decodebin2 ! tee name=t ! queue ! autoaudiosink t. ! queue ! audioconvert ! goom ! ffmpegcolorspace ! autovideosink
+ * ]| Play a song.ogg from local dir and render visualisations using the goom
+ * element.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
-- 
2.7.4