[glib/glib-2-38] Fix overloading of "source" and "target" terminology in GBinding

[Dan Winship <danw src gnome org>]

commit cbdb729e432956a6e1818e02ce57b24fbb374ebd
Author: Dan Winship <danw gnome org>
Date:   Fri Oct 4 12:58:48 2013 -0400

    Fix overloading of "source" and "target" terminology in GBinding
    
    GBindingTransformFunc called its arguments "source_value" and
    "target_value", but in the transform_from function of a bidirectional
    binding, "source_value" comes from the target object, and
    "target_value" comes from the source object, which quickly gets
    confusing if you need to use g_binding_get_source(), etc, in the
    function.
    
    Of course developers can call their transform function arguments
    whatever they want, but many will copy from the headers/docs to start
    out, so use less confusing names here ("from_value" and "to_value").
    
    Also, fix the documentation to describe the bidirectional case
    correctly.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=709440

 gobject/gbinding.c      |   44 ++++++++++++++++++++++----------------------
 gobject/gbinding.h      |   17 ++++++++++-------
 gobject/tests/binding.c |   24 ++++++++++++------------
 3 files changed, 44 insertions(+), 41 deletions(-)
---
diff --git a/gobject/gbinding.c b/gobject/gbinding.c
index 6fc8474..c8c8fa3 100644
--- a/gobject/gbinding.c
+++ b/gobject/gbinding.c
@@ -360,8 +360,8 @@ on_source_notify (GObject    *gobject,
                   GBinding   *binding)
 {
   const gchar *p_name;
-  GValue source_value = G_VALUE_INIT;
-  GValue target_value = G_VALUE_INIT;
+  GValue from_value = G_VALUE_INIT;
+  GValue to_value = G_VALUE_INIT;
   gboolean res;
 
   if (binding->is_frozen)
@@ -372,27 +372,27 @@ on_source_notify (GObject    *gobject,
   if (p_name != binding->source_property)
     return;
 
-  g_value_init (&source_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
-  g_value_init (&target_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
+  g_value_init (&from_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
+  g_value_init (&to_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
 
-  g_object_get_property (binding->source, binding->source_pspec->name, &source_value);
+  g_object_get_property (binding->source, binding->source_pspec->name, &from_value);
 
   res = binding->transform_s2t (binding,
-                                &source_value,
-                                &target_value,
+                                &from_value,
+                                &to_value,
                                 binding->transform_data);
   if (res)
     {
       binding->is_frozen = TRUE;
 
-      g_param_value_validate (binding->target_pspec, &target_value);
-      g_object_set_property (binding->target, binding->target_pspec->name, &target_value);
+      g_param_value_validate (binding->target_pspec, &to_value);
+      g_object_set_property (binding->target, binding->target_pspec->name, &to_value);
 
       binding->is_frozen = FALSE;
     }
 
-  g_value_unset (&source_value);
-  g_value_unset (&target_value);
+  g_value_unset (&from_value);
+  g_value_unset (&to_value);
 }
 
 static void
@@ -401,8 +401,8 @@ on_target_notify (GObject    *gobject,
                   GBinding   *binding)
 {
   const gchar *p_name;
-  GValue source_value = G_VALUE_INIT;
-  GValue target_value = G_VALUE_INIT;
+  GValue from_value = G_VALUE_INIT;
+  GValue to_value = G_VALUE_INIT;
   gboolean res;
 
   if (binding->is_frozen)
@@ -413,27 +413,27 @@ on_target_notify (GObject    *gobject,
   if (p_name != binding->target_property)
     return;
 
-  g_value_init (&source_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
-  g_value_init (&target_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
+  g_value_init (&from_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
+  g_value_init (&to_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
 
-  g_object_get_property (binding->target, binding->target_pspec->name, &source_value);
+  g_object_get_property (binding->target, binding->target_pspec->name, &from_value);
 
   res = binding->transform_t2s (binding,
-                                &source_value,
-                                &target_value,
+                                &from_value,
+                                &to_value,
                                 binding->transform_data);
   if (res)
     {
       binding->is_frozen = TRUE;
 
-      g_param_value_validate (binding->source_pspec, &target_value);
-      g_object_set_property (binding->source, binding->source_pspec->name, &target_value);
+      g_param_value_validate (binding->source_pspec, &to_value);
+      g_object_set_property (binding->source, binding->source_pspec->name, &to_value);
 
       binding->is_frozen = FALSE;
     }
 
-  g_value_unset (&source_value);
-  g_value_unset (&target_value);
+  g_value_unset (&from_value);
+  g_value_unset (&to_value);
 }
 
 static inline void
diff --git a/gobject/gbinding.h b/gobject/gbinding.h
index e49ad6d..82677ca 100644
--- a/gobject/gbinding.h
+++ b/gobject/gbinding.h
@@ -51,13 +51,16 @@ typedef struct _GBinding        GBinding;
 /**
  * GBindingTransformFunc:
  * @binding: a #GBinding
- * @source_value: the value of the source property
- * @target_value: the value of the target property
+ * @from_value: the #GValue containing the value to transform
+ * @to_value: the #GValue in which to store the transformed value
  * @user_data: data passed to the transform function
  *
- * A function to be called to transform the source property of @source
- * from @source_value into the target property of @target
- * using @target_value.
+ * A function to be called to transform @from_value to @to_value. If
+ * this is the @transform_to function of a binding, then @from_value
+ * is the @source_property on the @source object, and @to_value is the
+ * @target_property on the @target object. If this is the
+ * @transform_from function of a %G_BINDING_BIDIRECTIONAL binding,
+ * then those roles are reversed.
  *
  * Return value: %TRUE if the transformation was successful, and %FALSE
  *   otherwise
@@ -65,8 +68,8 @@ typedef struct _GBinding        GBinding;
  * Since: 2.26
  */
 typedef gboolean (* GBindingTransformFunc) (GBinding     *binding,
-                                            const GValue *source_value,
-                                            GValue       *target_value,
+                                            const GValue *from_value,
+                                            GValue       *to_value,
                                             gpointer      user_data);
 
 /**
diff --git a/gobject/tests/binding.c b/gobject/tests/binding.c
index 1b45367..5f87e84 100644
--- a/gobject/tests/binding.c
+++ b/gobject/tests/binding.c
@@ -237,44 +237,44 @@ binding_target_init (BindingTarget *self)
 
 static gboolean
 celsius_to_fahrenheit (GBinding     *binding,
-                       const GValue *source_value,
-                       GValue       *target_value,
+                       const GValue *from_value,
+                       GValue       *to_value,
                        gpointer      user_data G_GNUC_UNUSED)
 {
   gdouble celsius, fahrenheit;
 
-  g_assert (G_VALUE_HOLDS (source_value, G_TYPE_DOUBLE));
-  g_assert (G_VALUE_HOLDS (target_value, G_TYPE_DOUBLE));
+  g_assert (G_VALUE_HOLDS (from_value, G_TYPE_DOUBLE));
+  g_assert (G_VALUE_HOLDS (to_value, G_TYPE_DOUBLE));
 
-  celsius = g_value_get_double (source_value);
+  celsius = g_value_get_double (from_value);
   fahrenheit = (9 * celsius / 5) + 32.0;
 
   if (g_test_verbose ())
     g_print ("Converting %.2fC to %.2fF\n", celsius, fahrenheit);
 
-  g_value_set_double (target_value, fahrenheit);
+  g_value_set_double (to_value, fahrenheit);
 
   return TRUE;
 }
 
 static gboolean
 fahrenheit_to_celsius (GBinding     *binding,
-                       const GValue *source_value,
-                       GValue       *target_value,
+                       const GValue *from_value,
+                       GValue       *to_value,
                        gpointer      user_data G_GNUC_UNUSED)
 {
   gdouble celsius, fahrenheit;
 
-  g_assert (G_VALUE_HOLDS (source_value, G_TYPE_DOUBLE));
-  g_assert (G_VALUE_HOLDS (target_value, G_TYPE_DOUBLE));
+  g_assert (G_VALUE_HOLDS (from_value, G_TYPE_DOUBLE));
+  g_assert (G_VALUE_HOLDS (to_value, G_TYPE_DOUBLE));
 
-  fahrenheit = g_value_get_double (source_value);
+  fahrenheit = g_value_get_double (from_value);
   celsius = 5 * (fahrenheit - 32.0) / 9;
 
   if (g_test_verbose ())
     g_print ("Converting %.2fF to %.2fC\n", fahrenheit, celsius);
 
-  g_value_set_double (target_value, celsius);
+  g_value_set_double (to_value, celsius);
 
   return TRUE;
 }