Scale: Fix documentation of digits per last revert

Revert doc changes that were for the behavioural change just reverted.

Add a clarifying note that, under the original behaviour, :digits only
rounds the Adjustment if :draw-value is TRUE at the time of the change.

https://bugzilla.gnome.org/show_bug.cgi?id=781605
https://bugzilla.gnome.org/show_bug.cgi?id=358970

diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index 5f7720ac508a6715b1271a626a27baf04e4f5f80..ea58d661850e6839f3c2ac81a50954228d499ddb 100644 (file)
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -762,17 +762,10 @@ gtk_scale_class_init (GtkScaleClass *class)
                   G_TYPE_STRING, 1,
                   G_TYPE_DOUBLE);
 
-  /**
-   * GtkScale:digits:
-   *
-   * The number of decimal places to which the value is rounded when it is
-   * changed. This also sets the number of digits shown in the displayed value
-   * when using the default handler for the #GtkScale::format-value signal.
-   */
   properties[PROP_DIGITS] =
       g_param_spec_int ("digits",
                         P_("Digits"),
-                        P_("The number of decimal places to which the value is rounded"),
+                        P_("The number of decimal places that are displayed in the value"),
                         -1, MAX_DIGITS,
                         1,
                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
@@ -1120,11 +1113,13 @@ gtk_scale_new_with_range (GtkOrientation orientation,
 /**
  * gtk_scale_set_digits:
  * @scale: a #GtkScale
- * @digits: the number of decimal places to which the value will be rounded
+ * @digits: the number of decimal places to display,
+ *     e.g. use 1 to display 1.0, 2 to display 1.00, etc
  *
- * Sets the number of decimal places to which the value is rounded when it is
- * changed. This also sets the number of digits shown in the displayed value
- * when using the default handler for the #GtkScale::format-value signal.
+ * Sets the number of decimal places that are displayed in the value. Also
+ * causes the value of the adjustment to be rounded to this number of digits
+ * whenever it is changed, so the retrieved value matches the displayed one, if
+ * #GtkScale:draw-value is TRUE at the time of the change.
  *
  * Note that rounding to a small number of digits can interfere with
  * the smooth autoscrolling that is built into #GtkScale. As an alternative,
@@ -1162,10 +1157,9 @@ gtk_scale_set_digits (GtkScale *scale,
  * gtk_scale_get_digits:
  * @scale: a #GtkScale
  *
- * Gets the number of decimal places to which the value is rounded on change.
- * This number is also used by the default #GtkScale::format-value handler.
+ * Gets the number of decimal places that are displayed in the value.
  *
- * Returns: the number of decimal places
+ * Returns: the number of decimal places that are displayed
  */
 gint
 gtk_scale_get_digits (GtkScale *scale)
@@ -1963,7 +1957,8 @@ weed_out_neg_zero (gchar *str,
 }
 
 /*
- * Emits the #GtkScale::format-value signal.
+ * Emits #GtkScale:format-value signal to format the value;
+ * if no user signal handlers, falls back to a default format.
  *
  * Returns: formatted value
  */