From 06cf9deafefccd564a5572bd69dd1739c50d33fe Mon Sep 17 00:00:00 2001
From: Stefan Sauer <ensonic@users.sf.net>
Date: Thu, 10 Jan 2013 11:33:42 +0100
Subject: [PATCH] docs: improve api docs for controlsource and -binding

---
 gst/gstcontrolbinding.c |  5 ++++-
 gst/gstcontrolsource.c  | 22 ++++++++++------------
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/gst/gstcontrolbinding.c b/gst/gstcontrolbinding.c
index ab1d45c9a3..67a7f7d614 100644
--- a/gst/gstcontrolbinding.c
+++ b/gst/gstcontrolbinding.c
@@ -23,7 +23,10 @@
  * SECTION:gstcontrolbinding
  * @short_description: attachment for control source sources
  *
- * A value mapping object that attaches control sources to gobject properties.
+ * A base class for value mapping objects that attaches control sources to gobject
+ * properties. Such an object is taking one or more #GstControlSource instances,
+ * combines them and maps the resulting value to the type and value range of the
+ * bound property.
  */
 /* FIXME(ensonic): should we make gst_object_add_control_binding() internal
  * - we create the control_binding for a certain object anyway
diff --git a/gst/gstcontrolsource.c b/gst/gstcontrolsource.c
index 24f0d015df..c7b134d107 100644
--- a/gst/gstcontrolsource.c
+++ b/gst/gstcontrolsource.c
@@ -25,20 +25,18 @@
  * @short_description: base class for control source sources
  *
  * The #GstControlSource is a base class for control value sources that could
- * be used by #GstController to get timestamp-value pairs.
+ * be used by #GstController to get timestamp-value pairs. A control source
+ * essentially is a function over time, returning gloat values between 0.0 and 1.0.
  *
- * A #GstControlSource is used by first getting an instance, binding it to a
- * #GParamSpec (for example by using gst_controller_set_control_source()) and
- * then by having it used by the #GstController or calling
- * gst_control_source_get_value() or gst_control_source_get_value_array().
- *
- * For implementing a new #GstControlSource one has to implement a
- * #GstControlSourceBind method, which will depending on the #GParamSpec set up
- * the control source for use and sets the #GstControlSourceGetValue and
- * #GstControlSourceGetValueArray functions. These are then used by
- * gst_control_source_get_value() or gst_control_source_get_value_array()
- * to get values for specific timestamps.
+ * A #GstControlSource is used by first getting an instance of a specific
+ * control-source, creating a binding for the control-source to the target property
+ * of the element and then adding the binding to the element. The binding will
+ * convert the data types and value range to fit to the bound property.
  *
+ * For implementing a new #GstControlSource one has to implement
+ * #GstControlSourceGetValue and #GstControlSourceGetValueArray functions.
+ * These are then used by gst_control_source_get_value() and
+ * gst_control_source_get_value_array() to get values for specific timestamps.
  */
 
 #include "gst_private.h"