docs: misc. mixer docs improvements

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

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

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