Update and add documentation for platform specific plugins (sys).

Link to properties. Correct titles for examples. Fix examples.

15 files changed, 92 insertions, 169 deletions

diff --git a/sys/directdraw/gstdirectdrawsink.c b/sys/directdraw/gstdirectdrawsink.c
index caa28005..26babd90 100644
--- a/sys/directdraw/gstdirectdrawsink.c
+++ b/sys/directdraw/gstdirectdrawsink.c
@@ -25,21 +25,17 @@
 /**
  * SECTION:element-directdrawsink
  *
- * <refsect2>
- * <para>
  * DirectdrawSink renders video RGB frames to any win32 window. This element
- * can receive a window ID from the application through the XOverlay interface
+ * can receive a window ID from the application through the #XOverlay interface
  * and will then render video frames in this window.
  * If no Window ID was provided by the application, the element will create its
  * own internal window and render into it.
- * </para>
- * <title>Examples</title>
- * <para>
- * Here is a simple pipeline to test the sink :
- * <programlisting>
+ *
+ * <refsect2>
+ * <title>Example pipelines</title>
+ * |[
  * gst-launch-0.10 -v videotestsrc ! directdrawsink
- * </programlisting>
- * </para>
+ * ]| a simple pipeline to test the sink
  * </refsect2>
  */
 
diff --git a/sys/directsound/gstdirectsoundsink.c b/sys/directsound/gstdirectsoundsink.c
index bb9d38c6..037a72a5 100644
--- a/sys/directsound/gstdirectsoundsink.c
+++ b/sys/directsound/gstdirectsoundsink.c
@@ -27,32 +27,23 @@
 
 /**
  * SECTION:element-directsoundsink
- * @short_description: output sound using Directsound API
  *
- * <refsect2>
- * <para>
  * This element lets you output sound using the DirectSound API.
- * </para>
- * <para>
+ *
  * Note that you should almost always use generic audio conversion elements
  * like audioconvert and audioresample in front of an audiosink to make sure
  * your pipeline works under all circumstances (those conversion elements will
  * act in passthrough-mode if no conversion is necessary).
- * </para>
+ *
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch-0.10 -v audiotestsrc ! audioconvert ! volume volume=0.1 ! directsoundsink
- * </programlisting>
- * will output a sine wave (continuous beep sound) to your sound card (with
+ * ]| will output a sine wave (continuous beep sound) to your sound card (with
  * a very low volume as precaution).
- * </para>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch-0.10 -v filesrc location=music.ogg ! decodebin ! audioconvert ! audioresample ! directsoundsink
- * </programlisting>
- * will play an Ogg/Vorbis audio file and output it.
- * </para>
+ * ]| will play an Ogg/Vorbis audio file and output it.
  * </refsect2>
  */
 
diff --git a/sys/oss/gstossmixerelement.c b/sys/oss/gstossmixerelement.c
index 3ca3abb5..0988e367 100644
--- a/sys/oss/gstossmixerelement.c
+++ b/sys/oss/gstossmixerelement.c
@@ -19,15 +19,13 @@
 
 /**
  * SECTION:element-ossmixer
- * @short_description: element to control sound input and output levels with OSS
  *
- * <refsect2>
- * <para>
  * This element lets you adjust sound input and output levels with the
- * Open Sound System (OSS). It supports the GstMixer interface, which can be
+ * Open Sound System (OSS). It supports the #GstMixer interface, which can be
  * used to obtain a list of available mixer tracks. Set the mixer element to
- * READY state before using the GstMixer interface on it.
- * </para>
+ * READY state before using the #GstMixer interface on it.
+ *
+ * <refsect2>
  * <title>Example pipelines</title>
  * <para>
  * ossmixer can't be used in a sensible way in gst-launch.
diff --git a/sys/oss/gstosssink.c b/sys/oss/gstosssink.c
index 43fc167a..c508140c 100644
--- a/sys/oss/gstosssink.c
+++ b/sys/oss/gstosssink.c
@@ -22,32 +22,23 @@
 
 /**
  * SECTION:element-osssink
- * @short_description: output sound using OSS
  *
- * <refsect2>
- * <para>
  * This element lets you output sound using the Open Sound System (OSS).
- * </para>
- * <para>
+ *
  * Note that you should almost always use generic audio conversion elements
  * like audioconvert and audioresample in front of an audiosink to make sure
  * your pipeline works under all circumstances (those conversion elements will
  * act in passthrough-mode if no conversion is necessary).
- * </para>
+ *
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch -v audiotestsrc ! audioconvert ! volume volume=0.1 ! osssink
- * </programlisting>
- * will output a sine wave (continuous beep sound) to your sound card (with
+ * ]| will output a sine wave (continuous beep sound) to your sound card (with
  * a very low volume as precaution).
- * </para>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch -v filesrc location=music.ogg ! decodebin ! audioconvert ! audioresample ! osssink
- * </programlisting>
- * will play an Ogg/Vorbis audio file and output it using the Open Sound System.
- * </para>
+ * ]| will play an Ogg/Vorbis audio file and output it using the Open Sound System.
  * </refsect2>
  */
 
@@ -197,6 +188,7 @@ gst_oss_sink_base_init (gpointer g_class)
   gst_element_class_add_pad_template (element_class,
       gst_static_pad_template_get (&osssink_sink_factory));
 }
+
 static void
 gst_oss_sink_class_init (GstOssSinkClass * klass)
 {
diff --git a/sys/oss/gstosssrc.c b/sys/oss/gstosssrc.c
index 64b3736e..026ba2a4 100644
--- a/sys/oss/gstosssrc.c
+++ b/sys/oss/gstosssrc.c
@@ -22,21 +22,16 @@
 
 /**
  * SECTION:element-osssrc
- * @short_description: record sound from your sound card using OSS
  *
- * <refsect2>
- * <para>
  * This element lets you record sound using the Open Sound System (OSS).
- * </para>
+ *
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch -v osssrc ! audioconvert ! vorbisenc ! oggmux ! filesink location=mymusic.ogg
- * </programlisting>
- * will record sound from your sound card using OSS and encode it to an
+ * ]| will record sound from your sound card using OSS and encode it to an
  * Ogg/Vorbis file (this will only work if your mixer settings are right
  * and the right inputs enabled etc.)
- * </para>
  * </refsect2>
  */
 
@@ -147,6 +142,7 @@ gst_oss_src_base_init (gpointer g_class)
   gst_element_class_add_pad_template (element_class,
       gst_static_pad_template_get (&osssrc_src_factory));
 }
+
 static void
 gst_oss_src_class_init (GstOssSrcClass * klass)
 {
diff --git a/sys/osxaudio/gstosxaudio.c b/sys/osxaudio/gstosxaudio.c
index 262c7d91..1ddfce41 100644
--- a/sys/osxaudio/gstosxaudio.c
+++ b/sys/osxaudio/gstosxaudio.c
@@ -23,26 +23,6 @@
  *
  */
 
-/**
- * SECTION:element-osxaudiosink
- * @short_description: play audio to an CoreAudio device
- *
- * <refsect2>
- * <para>
- * This element renders raw audio samples using the CoreAudio api.
- * </para>
- * <title>Example pipelines</title>
- * <para>
- * Play an Ogg/Vorbis file.
- * </para>
- * <programlisting>
- * gst-launch -v filesrc location=sine.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! osxaudiosink
- * </programlisting>
- * </refsect2>
- *
- * Last reviewed on 2006-03-01 (0.10.4)
- */
-
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/sys/osxaudio/gstosxaudiosink.c b/sys/osxaudio/gstosxaudiosink.c
index aec8874d..9447e652 100644
--- a/sys/osxaudio/gstosxaudiosink.c
+++ b/sys/osxaudio/gstosxaudiosink.c
@@ -47,16 +47,18 @@
  */
 
 /**
- * SECTION:element-plugin
+ * SECTION:element-osxaudiosink
+ *
+ * This element renders raw audio samples using the CoreAudio api.
  *
  * <refsect2>
- * <title>Example launch line</title>
- * <para>
- * <programlisting>
- * gst-launch -v -m audiotestsrc ! audioconvert ! osxaudiosink
- * </programlisting>
- * </para>
+ * <title>Example pipelines</title>
+ * |[
+ * gst-launch filesrc location=sine.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! osxaudiosink
+ * ]| Play an Ogg/Vorbis file.
  * </refsect2>
+ *
+ * Last reviewed on 2006-03-01 (0.10.4)
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/sys/osxaudio/gstosxaudiosrc.c b/sys/osxaudio/gstosxaudiosrc.c
index 1d99e8d8..9acf4405 100644
--- a/sys/osxaudio/gstosxaudiosrc.c
+++ b/sys/osxaudio/gstosxaudiosrc.c
@@ -43,15 +43,15 @@
  */
 
 /**
- * SECTION:element-plugin
+ * SECTION:element-osxaudiosrc
+ *
+ * This element captures raw audio samples using the CoreAudio api.
  *
  * <refsect2>
  * <title>Example launch line</title>
- * <para>
- * <programlisting>
- * gst-launch -v -m osxaudiosrc ! fakesink
- * </programlisting>
- * </para>
+ * |[
+ * gst-launch osxaudiosrc ! wavenc ! filesink location=audio.wav
+ * ]|
  * </refsect2>
  */
 
diff --git a/sys/osxvideo/osxvideosink.m b/sys/osxvideo/osxvideosink.m
index a72171ee..3022197d 100644
--- a/sys/osxvideo/osxvideosink.m
+++ b/sys/osxvideo/osxvideosink.m
@@ -26,23 +26,19 @@
 /**
  * SECTION:element-osxvideosink
  *
- * <refsect2>
- * <para>
  * The OSXVideoSink renders video frames to a MacOSX window. The video output
  * can be directed to a window embedded in an existing NSApp. This can be done
- * by setting the "embed" property to #TRUE. When the NSView to be embedded is
- * created an element #GstMessage with a name of 'have-ns-view' will be created
- * and posted on the bus. The pointer to the NSView to embed will be in the
- * 'nsview' field of that message. If no embedding is requested, the plugin will
- * create a standalone window.
- * </para>
+ * by setting the #GstOSXVideoSink:embed property to %TRUE. When the NSView to
+ * be embedded is created an element #GstMessage with a name of 'have-ns-view'
+ * will be created and posted on the bus. The pointer to the NSView to embed
+ * will be in the 'nsview' field of that message. If no embedding is requested,
+ * the plugin will create a standalone window.
+ *
+ * <refsect2>
  * <title>Examples</title>
- * <para>
- * Simple timeline to test the sink :
- * <programlisting>
- * gst-launch-0.10 -v videotestsrc ! osxvideosink
- * </programlisting>
- * </para>
+ * |[
+ * gst-launch-0.10 videotestsrc ! osxvideosink
+ * ]| test the sink
  * </refsect2>
  */
 
diff --git a/sys/sunaudio/gstsunaudiomixer.c b/sys/sunaudio/gstsunaudiomixer.c
index 4789550a..f7dd0d9b 100644
--- a/sys/sunaudio/gstsunaudiomixer.c
+++ b/sys/sunaudio/gstsunaudiomixer.c
@@ -22,12 +22,8 @@
 /**
  * SECTION:element-sunaudiomixer
  *
- * <refsect2>
- * <para>
  * sunaudiomixer is an mixer that controls the sound input and output
  * levels with the Sun Audio interface available in Solaris.
- * </para>
- * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/sys/sunaudio/gstsunaudiosink.c b/sys/sunaudio/gstsunaudiosink.c
index 6718f701..8bf129eb 100644
--- a/sys/sunaudio/gstsunaudiosink.c
+++ b/sys/sunaudio/gstsunaudiosink.c
@@ -24,17 +24,14 @@
 /**
  * SECTION:element-sunaudiosink
  *
- * <refsect2>
- * <para>
  * sunaudiosink is an audio sink designed to work with the Sun Audio
  * interface available in Solaris.
- * </para>
+ *
+ * <refsect2>
  * <title>Example launch line</title>
- * <para>
- * <programlisting>
- * gst-launch -v sinesrc ! sunaudiosink
- * </programlisting>
- * </para>
+ * |[
+ * gst-launch audiotestsrc volume=0.5 ! sunaudiosink
+ * ]|
  * </refsect2>
  */
 
diff --git a/sys/sunaudio/gstsunaudiosrc.c b/sys/sunaudio/gstsunaudiosrc.c
index 470c9812..9f8ecc44 100644
--- a/sys/sunaudio/gstsunaudiosrc.c
+++ b/sys/sunaudio/gstsunaudiosrc.c
@@ -24,18 +24,14 @@
 /**
  * SECTION:element-sunaudiosrc
  *
- * <refsect2>
- * <para>
  * sunaudiosrc is an audio source designed to work with the Sun Audio
  * interface available in Solaris.
- * </para>
+ *
+ * <refsect2>
  * <title>Example launch line</title>
- * <para>
- * <programlisting>
- * 
- * gst-launch sunaudiosrc ! filesink location=outfile 
- * </programlisting>
- * </para>
+ * |[
+ * gst-launch sunaudiosrc ! wavenc ! filesink location=audio.wav
+ * ]|
  * </refsect2>
  */
 
diff --git a/sys/v4l2/gstv4l2src.c b/sys/v4l2/gstv4l2src.c
index 4520f970..6983d69f 100644
--- a/sys/v4l2/gstv4l2src.c
+++ b/sys/v4l2/gstv4l2src.c
@@ -24,23 +24,19 @@
 /**
  * SECTION:element-v4l2src
  *
+ * v4l2src can be used to capture video from v4l2 devices, like webcams and tv
+ * cards.
+ *
  * <refsect2>
- * v4l2src can be used to capture video from v4l2 devices, like webcams and tv cards.
  * <title>Example launch lines</title>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch v4l2src ! xvimagesink
- * </programlisting>
- * This pipeline shows the video captured from /dev/video0 tv card and for
+ * ]| This pipeline shows the video captured from /dev/video0 tv card and for
  * webcams.
- * </para>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch-0.10 v4l2src ! jpegdec ! xvimagesink
- * </programlisting>
- * This pipeline shows the video captured from a webcam that delivers jpeg
+ * ]| This pipeline shows the video captured from a webcam that delivers jpeg
  * images.
- * </para>
  * </refsect2>
  */
 
diff --git a/sys/waveform/gstwaveformsink.c b/sys/waveform/gstwaveformsink.c
index e709d649..a5614168 100644
--- a/sys/waveform/gstwaveformsink.c
+++ b/sys/waveform/gstwaveformsink.c
@@ -21,32 +21,23 @@
 
 /**
  * SECTION:element-waveformsink
- * @short_description: output sound using WaveForm API
  *
- * <refsect2>
- * <para>
- * This element lets you output sound using the WaveForm API.
- * </para>
- * <para>
+ * This element lets you output sound using the Windows WaveForm API.
+ *
  * Note that you should almost always use generic audio conversion elements
  * like audioconvert and audioresample in front of an audiosink to make sure
  * your pipeline works under all circumstances (those conversion elements will
  * act in passthrough-mode if no conversion is necessary).
- * </para>
+ *
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch-0.10 -v audiotestsrc ! audioconvert ! volume volume=0.1 ! waveformsink
- * </programlisting>
- * will output a sine wave (continuous beep sound) to your sound card (with
+ * ]| will output a sine wave (continuous beep sound) to your sound card (with
  * a very low volume as precaution).
- * </para>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch-0.10 -v filesrc location=music.ogg ! decodebin ! audioconvert ! audioresample ! waveformsink
- * </programlisting>
- * will play an Ogg/Vorbis audio file and output it.
- * </para>
+ * ]| will play an Ogg/Vorbis audio file and output it.
  * </refsect2>
  */
 
@@ -435,8 +426,7 @@ gst_waveform_sink_unprepare (GstAudioSink * asink)
 
     for (index = 0; index < wfsink->buffer_count; index++) {
       if (wfsink->wave_buffers[index].dwFlags & WHDR_PREPARED) {
-        MMRESULT mmresult =
-            waveOutUnprepareHeader (wfsink->hwaveout,
+        MMRESULT mmresult = waveOutUnprepareHeader (wfsink->hwaveout,
             &wfsink->wave_buffers[index], sizeof (WAVEHDR));
         if (mmresult != MMSYSERR_NOERROR) {
           waveOutGetErrorText (mmresult, wfsink->error_string,
diff --git a/sys/ximage/gstximagesrc.c b/sys/ximage/gstximagesrc.c
index 5f02b958..15288122 100644
--- a/sys/ximage/gstximagesrc.c
+++ b/sys/ximage/gstximagesrc.c
@@ -20,23 +20,18 @@
 
 /**
  * SECTION:element-ximagesrc
- * @short_description: a source that captures your X Display
  *
- * <refsect2>
- * <para>
  * This element captures your X Display and creates raw RGB video.  It uses
  * the XDamage extension if available to only capture areas of the screen that
  * have changed since the last frame.  It uses the XFixes extension if
  * available to also capture your mouse pointer.  By default it will fixate to
  * 25 frames per second.
- * </para>
+ *
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
- * <programlisting>
- * gst-launch -v ximagesrc ! video/x-raw-rgb,framerate=5/1 ! ffmpegcolorspace ! theoraenc ! oggmux ! filesink location=desktop.ogg
- * </programlisting>
- * Encodes your X display to an Ogg theora video at 5 frames per second.
- * </para>
+ * |[
+ * gst-launch ximagesrc ! video/x-raw-rgb,framerate=5/1 ! ffmpegcolorspace ! theoraenc ! oggmux ! filesink location=desktop.ogg
+ * ]| Encodes your X display to an Ogg theora video at 5 frames per second.
  * </refsect2>
  */
 
@@ -941,12 +936,14 @@ gst_ximage_src_get_caps (GstBaseSrc * bs)
   gint x, y, width, height;
 
   if ((!s->xcontext) && (!gst_ximage_src_open_display (s, s->display_name)))
-    return gst_caps_copy (gst_pad_get_pad_template_caps (GST_BASE_SRC (s)->
-            srcpad));
+    return
+        gst_caps_copy (gst_pad_get_pad_template_caps (GST_BASE_SRC
+            (s)->srcpad));
 
   if (!gst_ximage_src_recalc (s))
-    return gst_caps_copy (gst_pad_get_pad_template_caps (GST_BASE_SRC (s)->
-            srcpad));
+    return
+        gst_caps_copy (gst_pad_get_pad_template_caps (GST_BASE_SRC
+            (s)->srcpad));
 
   xcontext = s->xcontext;