From f4da218edd55e54e75e6c9485685eefc94432fce Mon Sep 17 00:00:00 2001
From: Jan Schmidt <thaytan@noraisin.net>
Date: Fri, 27 Feb 2009 11:39:56 +0000
Subject: [PATCH] dtsdec: Add some basic docs to the plugin

---
 docs/plugins/Makefile.am                      |  1 +
 .../plugins/gst-plugins-bad-plugins-docs.sgml |  1 +
 .../gst-plugins-bad-plugins-sections.txt      | 14 +++++++++++
 ext/dts/gstdtsdec.c                           | 25 ++++++++++++++++---
 4 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index c5504b19e1..5f78f46f8e 100644
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -96,6 +96,7 @@ EXTRA_HFILES = \
 	$(top_srcdir)/ext/celt/gstceltenc.h \
 	$(top_srcdir)/ext/dc1394/gstdc1394.h \
 	$(top_srcdir)/ext/directfb/dfbvideosink.h \
+	$(top_srcdir)/ext/dts/gstdtsdec.h \
 	$(top_srcdir)/ext/ivorbis/vorbisdec.h \
 	$(top_srcdir)/ext/jack/gstjackaudiosrc.h \
 	$(top_srcdir)/ext/jack/gstjackaudiosink.h \
diff --git a/docs/plugins/gst-plugins-bad-plugins-docs.sgml b/docs/plugins/gst-plugins-bad-plugins-docs.sgml
index 1b399ba571..fe2ddf24df 100644
--- a/docs/plugins/gst-plugins-bad-plugins-docs.sgml
+++ b/docs/plugins/gst-plugins-bad-plugins-docs.sgml
@@ -34,6 +34,7 @@
     <xi:include href="xml/element-deinterlace.xml" />
     <xi:include href="xml/element-dfbvideosink.xml" />
     <xi:include href="xml/element-dtmfsrc.xml" />
+    <xi:include href="xml/element-dtsdec.xml" />
     <xi:include href="xml/element-dvbsrc.xml" />
     <xi:include href="xml/element-dvdspu.xml" />
     <xi:include href="xml/element-festival.xml" />
diff --git a/docs/plugins/gst-plugins-bad-plugins-sections.txt b/docs/plugins/gst-plugins-bad-plugins-sections.txt
index a2829ef96e..bf07b16fc6 100644
--- a/docs/plugins/gst-plugins-bad-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-bad-plugins-sections.txt
@@ -248,6 +248,20 @@ gst_dtmf_src_get_type
 gst_dtmf_src_plugin_init
 </SECTION>
 
+<SECTION>
+<FILE>element-dtsdec</FILE>
+<TITLE>dtsdec</TITLE>
+GstDtsDec
+<SUBSECTION Standard>
+GstDtsDecClass
+gst_dtsdec_get_type
+GST_TYPE_DTSDEC
+GST_DTSDEC
+GST_DTSDEC_CLASS
+GST_IS_DTSDEC
+GST_IS_DTSDEC_CLASS
+</SECTION>
+
 <SECTION>
 <FILE>element-dvbsrc</FILE>
 <TITLE>dvbsrc</TITLE>
diff --git a/ext/dts/gstdtsdec.c b/ext/dts/gstdtsdec.c
index 58748e6cb2..5b85a80322 100644
--- a/ext/dts/gstdtsdec.c
+++ b/ext/dts/gstdtsdec.c
@@ -17,9 +17,20 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/* TODO: - Port to libdca API instead of relying on the compat header.
- *         libdca is the successor of libdts:
- *         http://www.videolan.org/developers/libdca.html
+/**
+ * SECTION:element-dtsdec
+ *
+ * Digital Theatre System (DTS) audio decoder
+ * 
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch dvdreadsrc title=1 ! mpegpsdemux ! dtsdec ! audioresample ! audioconvert ! alsasink
+ * ]| Play a DTS audio track from a dvd.
+ * |[
+ * gst-launch filesrc location=abc.dts ! dtsdec ! audioresample ! audioconvert ! alsasink
+ * ]| Decode a standalone file and play it.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
@@ -162,6 +173,14 @@ gst_dtsdec_class_init (GstDtsDecClass * klass)
 
   gstelement_class->change_state = gst_dtsdec_change_state;
 
+  /**
+   * GstDtsDec::drc
+   *
+   * Set to true to apply the recommended DTS dynamic range compression
+   * to the audio stream. Dynamic range compression makes loud sounds
+   * softer and soft sounds louder, so you can more easily listen
+   * to the stream without disturbing other people.
+   */
   g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_DRC,
       g_param_spec_boolean ("drc", "Dynamic Range Compression",
           "Use Dynamic Range Compression", FALSE, G_PARAM_READWRITE));