Merge branch 'gtk-jan2024_docs_tweaks' into 'main'

docs: Clarify child objects in GtkBuilder

See merge request GNOME/gtk!6945

gtk/gtkbuilder.c

@@ -99,9 +99,7 @@
  * Objects are described by `<object>` elements, which can contain
  * `<property>` elements to set properties, `<signal>` elements which
  * connect signals to handlers, and `<child>` elements, which describe
- * child objects (most often widgets inside a container, but also e.g.
- * actions in an action group, or columns in a tree model). A `<child>`
- * element contains an `<object>` element which describes the child object.
+ * child objects.
  *
  * Typically, the specific kind of object represented by an `<object>`
  * element is specified by the “class” attribute. If the type has not
@@ -173,6 +171,53 @@
  * exception to this rule is that an object has to be constructed before
  * it can be used as the value of a construct-only property.
  *
+ * ### Child objects
+ *
+ * Many widgets have properties for child widgets, such as
+ * [property@Gtk.Expander:child]. In this case, the preferred way to
+ * specify the child widget in a ui file is to simply set the property:
+ *
+ * ```xml
+ * <object class="GtkExpander">
+ *   <property name="child">
+ *     <object class="GtkLabel">
+ *     ...
+ *     </object>
+ *   </property>
+ * </object>
+ * ```
+ *
+ * Generic containers that can contain an arbitrary number of children,
+ * such as [class@Gtk.Box] instead use the `<child>` element. A `<child>`
+ * element contains an `<object>` element which describes the child object.
+ * Most often, child objects are widgets inside a container, but they can
+ * also be, e.g., actions in an action group, or columns in a tree model.
+ *
+ * Any object type that implements the [iface@Gtk.Buildable] interface can
+ * specify how children may be added to it. Since many objects and widgets that
+ * are included with GTK already implement the `GtkBuildable` interface,
+ * typically child objects can be added using the `<child>` element without
+ * having to be concerned about the underlying implementation.
+ *
+ * See the [`GtkWidget` documentation](class.Widget.html#gtkwidget-as-gtkbuildable)
+ * for many examples of using `GtkBuilder` with widgets, including setting
+ * child objects using the `<child>` element.
+ *
+ * A noteworthy special case to the general rule that only objects implementing
+ * `GtkBuildable` may specify how to handle the `<child>` element is that
+ * `GtkBuilder` provides special support for adding objects to a
+ * [class@Gio.ListStore] by using the `<child>` element. For instance:
+ *
+ * ```xml
+ * <object class="GListStore">
+ *   <property name="item-type">MyObject</property>
+ *   <child>
+ *     <object class="MyObject" />
+ *   </child>
+ *   ...
+ * </object>
+ * ```
+ *
  * ### Property bindings
  *
  * It is also possible to bind a property value to another object's
@@ -208,6 +253,11 @@
  * For more information, see the documentation of the
  * [method@GObject.Object.bind_property] method.
  *
+ * Please note that another way to set up bindings between objects in .ui files
+ * is to use the `GtkExpression` methodology. See the
+ * [`GtkExpression` documentation](class.Expression.html#gtkexpression-in-ui-files)
+ * for more information.
+ *
  * ### Internal children
  *
  * Sometimes it is necessary to refer to widgets which have implicitly

gtk/gtkexpression.c

@@ -150,9 +150,10 @@
  *   <constant type='gchararray'>Hello, world</constant>
  * ```
  *
- * To create a closure expression, use the `<closure>` element. The `type` and `function`
- * attributes specify what function to use for the closure, the content of the element
- * contains the expressions for the parameters. For instance:
+ * To create a closure expression, use the `<closure>` element. The `function`
+ * attribute specifies what function to use for the closure, and the `type`
+ * attribute specifies its return type. The content of the element contains the
+ * expressions for the parameters. For instance:
  *
  * ```xml
  *   <closure type='gchararray' function='combine_args_somehow'>
@@ -160,6 +161,22 @@
  *     <lookup type='GFile' name='size'>myfile</lookup>
  *   </closure>
  * ```
+ *
+ * To create a property binding, use the `<binding>` element in place of where a
+ * `<property>` tag would ordinarily be used. The `name` and `object` attributes are
+ * supported. The `name` attribute is required, and pertains to the applicable property
+ * name. The `object` attribute is optional. If provided, it will use the specified object
+ * as the `this` object when the expression is evaluated. Here is an example in which the
+ * `label` property of a `GtkLabel` is bound to the `string` property of another arbitrary
+ * object:
+ *
+ * ```xml
+ *   <object class='GtkLabel'>
+ *     <binding name='label'>
+ *       <lookup name='string'>some_other_object</lookup>
+ *     </binding>
+ *   </object>
+ * ```
  */
 
 typedef struct _WeakRefGuard WeakRefGuard;

gtk/gtkspinbutton.c

@@ -518,12 +518,10 @@ gtk_spin_button_class_init (GtkSpinButtonClass *class)
    * on_output (GtkSpinButton *spin,
    *            gpointer       data)
    * {
-   *    GtkAdjustment *adjustment;
    *    char *text;
    *    int value;
    *
-   *    adjustment = gtk_spin_button_get_adjustment (spin);
-   *    value = (int)gtk_adjustment_get_value (adjustment);
+   *    value = gtk_spin_button_get_value_as_int (spin);
    *    text = g_strdup_printf ("%02d", value);
    *    gtk_editable_set_text (GTK_EDITABLE (spin), text):
    *    g_free (text);