From 4cb197999ec58e50cdbc996c8b1f9f753b0a5b52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= <tim.muller@collabora.co.uk>
Date: Sat, 12 Dec 2009 18:58:39 +0000
Subject: [PATCH] docs: misc. mixer docs improvements

---
 gst-libs/gst/interfaces/mixer.c        | 17 +++++++++++++++++
 gst-libs/gst/interfaces/mixeroptions.c | 10 ++++++++++
 gst-libs/gst/interfaces/mixertrack.c   | 16 ++++++++++++++++
 3 files changed, 43 insertions(+)

diff --git a/gst-libs/gst/interfaces/mixer.c b/gst-libs/gst/interfaces/mixer.c
index 3546783473..57907c03c8 100644
--- a/gst-libs/gst/interfaces/mixer.c
+++ b/gst-libs/gst/interfaces/mixer.c
@@ -31,6 +31,23 @@
 /**
  * SECTION:gstmixer
  * @short_description: Interface for elements that provide mixer operations
+ * @see_also: alsamixer, oss4mixer, sunaudiomixer
+ *
+ * Basic interface for hardware mixer controls.
+ *
+ * Applications rarely need to use this interface, it is provided mainly
+ * for system-level mixer applets and the like. Volume control in playback
+ * applications should be done using a <classname>volume</classname>
+ * element or, if available, using the <quote>volume</quote> property of
+ * the audio sink element used (as provided by <classname>pulsesink</classname>
+ * for example), or even better: just use the <classname>playbin2</classname>
+ * element's <quote>volume</quote> property.
+ *
+ * Usage: In order to use the <classname>GstMixer</classname> interface, the
+ * element needs to be at least in READY state (so that the element has opened
+ * the mixer device). Once the element has been set to READY state or higher,
+ * it can be cast to a <classname>GstMixer</classname> using the GST_MIXER
+ * macro (in C) and the mixer API can be used.
  */
 
 #ifndef GST_DISABLE_DEPRECATED
diff --git a/gst-libs/gst/interfaces/mixeroptions.c b/gst-libs/gst/interfaces/mixeroptions.c
index b04f892230..01b75b433f 100644
--- a/gst-libs/gst/interfaces/mixeroptions.c
+++ b/gst-libs/gst/interfaces/mixeroptions.c
@@ -19,6 +19,16 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstmixeroptions
+ * @short_description: Multi-option mixer control
+ * @see_also: GstMixer, GstMixerTrack
+ *
+ * Mixer control object that allows switching between multiple options.
+ * Note that <classname>GstMixerOptions</classname> is a subclass of
+ * <classname>GstMixerTrack</classname>.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst-libs/gst/interfaces/mixertrack.c b/gst-libs/gst/interfaces/mixertrack.c
index 7a1584be10..108f7be0fe 100644
--- a/gst-libs/gst/interfaces/mixertrack.c
+++ b/gst-libs/gst/interfaces/mixertrack.c
@@ -19,6 +19,22 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstmixertrack
+ * @short_description: Basic mixer control object (volume slider, switch)
+ * @see_also: GstMixer, GstMixerOptions
+ *
+ * Basic mixer control object (note that it is a GObject and not a GstObject).
+ *
+ * A mixer track represents a single slider control of none, one or more
+ * channels. A mixer track with no channels is usually interpreted as a
+ * on/off switch control.
+ *
+ * Note the presence of both min_volume and max_volume fields. Applications
+ * must not assume that min_volume is 0 or max_volume is any particular
+ * value.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif