Update and add documentation for plugins with deps (ext).

Link to properties. Correct titles for examples. Document a few trivial cases. Keep lists in section file and docs/plugins/Makefile.am alphabetically ordered. Fix warnings that gtk-doc points out.

3 files changed, 17 insertions, 29 deletions

diff --git a/ext/hal/gsthalaudiosink.c b/ext/hal/gsthalaudiosink.c
index de4d8844..e010ea4e 100644
--- a/ext/hal/gsthalaudiosink.c
+++ b/ext/hal/gsthalaudiosink.c
@@ -21,27 +21,21 @@
 /**
  * SECTION:element-halaudiosink
  *
- * <refsect2>
- * <para>
  * HalAudioSink allows access to output of sound devices by specifying the
  * corresponding persistent Unique Device Id (UDI) from the Hardware Abstraction
- * Layer (HAL) in the <link linkend="GstHalAudioSrc--udi">udi</link> property.
+ * Layer (HAL) in the #GstHalAudioSink:udi property.
  * It currently always embeds alsasink or osssink as HAL doesn't support other
  * sound systems yet. You can also specify the UDI of a device that has ALSA or
  * OSS subdevices. If both are present ALSA is preferred.
- * </para>
+ *
+ * <refsect2>
  * <title>Examples</title>
- * <para>
- * To list the UDIs of all your ALSA output devices :
- * <programlisting>
+ * |[
  * hal-find-by-property --key alsa.type --string playback
- * </programlisting>
- * Here is a pipeline to test your sound output :
- * <programlisting>
+ * ]| list the UDIs of all your ALSA output devices
+ * |[
  * gst-launch -v audiotestsrc ! halaudiosink udi=/org/freedesktop/Hal/devices/pci_8086_27d8_alsa_playback_0
- * </programlisting>
- * This pipeline produces a test signal on the specified sound device.
- * </para>
+ * ]| test your soundcard by playing a test signal on the specified sound device.
  * </refsect2>
  */
 
diff --git a/ext/hal/gsthalaudiosrc.c b/ext/hal/gsthalaudiosrc.c
index 626e9d35..bd0a70b5 100644
--- a/ext/hal/gsthalaudiosrc.c
+++ b/ext/hal/gsthalaudiosrc.c
@@ -22,28 +22,22 @@
 /**
  * SECTION:element-halaudiosrc
  *
- * <refsect2>
- * <para>
  * HalAudioSrc allows access to input of sound devices by specifying the
  * corresponding persistent Unique Device Id (UDI) from the Hardware Abstraction
- * Layer (HAL) in the <link linkend="GstHalAudioSrc--udi">udi</link> property.
+ * Layer (HAL) in the #GstHalAudioSrc:udi property.
  * It currently always embeds alsasrc or osssrc as HAL doesn't support other
  * sound systems yet. You can also specify the UDI of a device that has ALSA or
  * OSS subdevices. If both are present ALSA is preferred.
- * </para>
+ *
+ * <refsect2>
  * <title>Examples</title>
- * <para>
- * To list the UDIs of all your ALSA input devices :
- * <programlisting>
+ * |[
  * hal-find-by-property --key alsa.type --string capture
- * </programlisting>
- * Here is a pipeline to test your sound input :
- * <programlisting>
+ * ]| list the UDIs of all your ALSA input devices
+ * |[
  * gst-launch -v halaudiosrc udi=/org/freedesktop/Hal/devices/pci_8086_27d8_alsa_capture_0 ! autoaudiosink
- * </programlisting>
- * You should now hear yourself with a small delay if you have a microphone
+ * ]| You should now hear yourself with a small delay if you have a microphone
  * connected to the specified sound device.
- * </para>
  * </refsect2>
  */
 
diff --git a/ext/hal/hal.c b/ext/hal/hal.c
index d23a91a6..b0e1d823 100644
--- a/ext/hal/hal.c
+++ b/ext/hal/hal.c
@@ -40,7 +40,7 @@ GST_DEBUG_CATEGORY_EXTERN (hal_debug);
 #define LIBHAL_FREE_DBUS_ERROR(e) dbus_error_free (e)
 #endif
 
-/**
+/*
  * gst_hal_get_alsa_element:
  * @ctx: a #LibHalContext which should be used for querying HAL.
  * @udi: a #gchar corresponding to the UDI you want to get.
@@ -130,7 +130,7 @@ gst_hal_get_alsa_element (LibHalContext * ctx, const gchar * udi,
   return string;
 }
 
-/**
+/*
  * gst_hal_get_oss_element:
  * @ctx: a #LibHalContext which should be used for querying HAL.
  * @udi: a #gchar corresponding to the UDI you want to get.
@@ -203,7 +203,7 @@ gst_hal_get_oss_element (LibHalContext * ctx, const gchar * udi,
   return string;
 }
 
-/**
+/*
  * gst_hal_get_string:
  * @udi: a #gchar corresponding to the UDI you want to get.
  * @device_type: a #GstHalDeviceType specifying the wanted device type.