plugins: add example launch lines and more explanation to the docs.

The plugins where almost undocumented :/ ...

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

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

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

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

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