[gimp] app, libgimpwidgets: update gimp_prop_foo_new() documentation comments.

[Jehan Pagès <jehanp src gnome org>]

commit 30e4826473aaca49d4e5425f81e427e79d52b4bd
Author: Jehan <jehan girinstud io>
Date:   Thu Feb 11 16:35:45 2016 +0100

    app, libgimpwidgets: update gimp_prop_foo_new() documentation comments.
    
    Explains what happens when NULL labels are used.

 app/widgets/gimppropwidgets.c    |   27 +++++++++++++++++++++++++++
 libgimpwidgets/gimppropwidgets.c |   12 ++++++++++++
 2 files changed, 39 insertions(+), 0 deletions(-)
---
diff --git a/app/widgets/gimppropwidgets.c b/app/widgets/gimppropwidgets.c
index eac1f57..cb25f05 100644
--- a/app/widgets/gimppropwidgets.c
+++ b/app/widgets/gimppropwidgets.c
@@ -85,6 +85,25 @@ static void         connect_notify     (GObject     *config,
 /*  expanding frame  */
 /*********************/
 
+/**
+ * gimp_prop_expanding_frame_new:
+ * @config:        #GimpConfig object to which property is attached.
+ * @property_name: Name of boolean property.
+ * @button_label:  Toggle widget title appearing as a frame title.
+ * @child:         Child #GtkWidget of the returned frame.
+ * @button:        Pointer to the #GtkCheckButton used as frame title
+ *                 if not #NULL.
+ *
+ * Creates a #GimpFrame containing @child, using a #GtkCheckButton as a
+ * title whose value is tied to the boolean @property_name.
+ * @child will be visible when @property_name is #TRUE, hidden otherwise.
+ * If @button_label is #NULL, the @property_name's nick will be used as
+ * label of the #GtkCheckButton title.
+ *
+ * Return value:  A new #GimpFrame widget.
+ *
+ * Since GIMP 2.4
+ */
 GtkWidget *
 gimp_prop_expanding_frame_new (GObject      *config,
                                const gchar  *property_name,
@@ -255,6 +274,8 @@ static void   gimp_prop_color_button_notify   (GObject    *config,
  *
  * Creates a #GimpColorPanel to set and display the value of a #GimpRGB
  * property.  Pressing the button brings up a color selector dialog.
+ * If @title is #NULL, the @property_name's nick will be used as label
+ * of the returned widget.
  *
  * Return value:  A new #GimpColorPanel widget.
  *
@@ -470,9 +491,15 @@ static void   gimp_prop_adjustment_notify   (GObject       *config,
  * gimp_prop_spin_scale_new:
  * @config:        #GimpConfig object to which property is attached.
  * @property_name: Name of gdouble property
+ * @label:         Label of the created #GimpSpinScale.
+ * @step_increment:
+ * @page_increment:
+ * @digits:
  *
  * Creates a #GimpSpinScale to set and display the value of a
  * gdouble property in a very space-efficient way.
+ * If @label is #NULL, the @property_name's nick will be used as label
+ * of the returned widget.
  *
  * Return value:  A new #GimpSpinScale widget.
  *
diff --git a/libgimpwidgets/gimppropwidgets.c b/libgimpwidgets/gimppropwidgets.c
index e8b5d25..8820d23 100644
--- a/libgimpwidgets/gimppropwidgets.c
+++ b/libgimpwidgets/gimppropwidgets.c
@@ -103,6 +103,8 @@ static void   gimp_prop_check_button_notify   (GObject    *config,
  *
  * Creates a #GtkCheckButton that displays and sets the specified
  * boolean property.
+ * If @label is #NULL, the @property_name's nick will be used as label
+ * of the returned button.
  *
  * Return value: The newly created #GtkCheckButton widget.
  *
@@ -211,6 +213,8 @@ static void   gimp_prop_enum_check_button_notify   (GObject    *config,
  * property of type Enum.  Note that this widget only allows two values
  * for the enum, one corresponding to the "checked" state and the
  * other to the "unchecked" state.
+ * If @label is #NULL, the @property_name's nick will be used as label
+ * of the returned button.
  *
  * Return value: The newly created #GtkCheckButton widget.
  *
@@ -764,6 +768,8 @@ static void  gimp_prop_radio_button_notify   (GObject     *config,
  * the specified enum property.  The @minimum and @maximum arguments
  * allow only a subset of the enum to be used.  If the two arguments
  * are equal (e.g., 0, 0), then the full range of the enum will be used.
+ * If @title is #NULL, the @property_name's nick will be used as label
+ * of the returned frame.
  *
  * Return value: A #GimpFrame containing the radio buttons.
  *
@@ -971,6 +977,8 @@ gimp_prop_enum_label_notify (GObject    *config,
  *
  * Creates a pair of radio buttons which function to set and display
  * the specified boolean property.
+ * If @title is #NULL, the @property_name's nick will be used as label
+ * of the returned frame.
  *
  * Return value: A #GimpFrame containing the radio buttons.
  *
@@ -1316,6 +1324,8 @@ gimp_prop_hscale_new (GObject     *config,
  * Creates a #libgimpwidgets-gimpscaleentry (slider and spin button)
  * to set and display the value of the specified double property.  See
  * gimp_scale_entry_new() for more information.
+ * If @label is #NULL, the @property_name's nick will be used as label
+ * of the returned object.
  *
  * Note that the @scale_limits boolean is the inverse of
  * gimp_scale_entry_new()'s "constrain" parameter.
@@ -3971,6 +3981,8 @@ static void   gimp_prop_expander_notify (GObject     *config,
  * Creates a #GtkExpander controlled by the specified boolean property.
  * A value of %TRUE for the property corresponds to the expanded state
  * for the widget.
+ * If @label is #NULL, the @property_name's nick will be used as label
+ * of the returned widget.
  *
  * Return value:  A new #GtkExpander widget.
  *