[gtk/ebassi/gidocgen: 192/483] box: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit 507de785b4eb05eb3de0d5d780645d54a535b960
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Feb 25 23:16:28 2021 -0500

    box: Convert docs
    
    Convert link format, add an example image, add
    property annotations. General cleanup.

 gtk/gtkbox.c | 152 +++++++++++++++++++++++++++++++++--------------------------
 1 file changed, 86 insertions(+), 66 deletions(-)
---
diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index d30dbfb8bf..ea24cf7637 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -23,38 +23,40 @@
  */
 
 /**
- * SECTION:gtkbox
- * @Short_description: A container for packing widgets in a single row or column
- * @Title: GtkBox
- * @See_also: #GtkGrid
+ * GtkBox:
  *
- * The GtkBox widget arranges child widgets into a single row or column,
- * depending upon the value of its #GtkOrientable:orientation property. Within
- * the other dimension, all children are allocated the same size. Of course,
- * the #GtkWidget:halign and #GtkWidget:valign properties can be used on
- * the children to influence their allocation.
+ * The `GtkBox` widget arranges child widgets into a single row or column.
  *
- * Use repeated calls to gtk_box_append() to pack widgets into a GtkBox
- * from start to end. Use gtk_box_remove() to remove widgets from the GtkBox.
- * gtk_box_insert_child_after() can be used to add a child at a particular position.
+ * ![An example GtkBox](box.png)
  *
- * Use gtk_box_set_homogeneous() to specify whether or not all children
- * of the GtkBox are forced to get the same amount of space.
+ * Whether it is a row or column depends on the value of its
+ * [property@Gtk.Orientable:orientation] property. Within the other
+ * dimension, all children are allocated the same size. Of course, the
+ * [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties
+ * can be used on the children to influence their allocation.
  *
- * Use gtk_box_set_spacing() to determine how much space will be
- * minimally placed between all children in the GtkBox. Note that
- * spacing is added between the children.
+ * Use repeated calls to [method Gtk Box.append] to pack widgets into a
+ * `GtkBox` from start to end. Use [method Gtk Box.remove] to remove widgets
+ * from the `GtkBox`. [method Gtk Box.insert_child_after] can be used to add
+ * a child at a particular position.
  *
- * Use gtk_box_reorder_child_after() to move a child to a different
+ * Use [method Gtk Box.set_homogeneous] to specify whether or not all children
+ * of the `GtkBox` are forced to get the same amount of space.
+ *
+ * Use [method Gtk Box.set_spacing] to determine how much space will be minimally
+ * placed between all children in the `GtkBox`. Note that spacing is added
+ * *between* the children.
+ *
+ * Use [method Gtk Box.reorder_child_after] to move a child to a different
  * place in the box.
  *
  * # CSS nodes
  *
- * GtkBox uses a single CSS node with name box.
+ * `GtkBox` uses a single CSS node with name box.
  *
  * # Accessibility
  *
- * GtkBox uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
+ * `GtkBox` uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 #include "config.h"
@@ -255,6 +257,11 @@ gtk_box_class_init (GtkBoxClass *class)
                                     PROP_ORIENTATION,
                                     "orientation");
 
+  /**
+   * GtkBox:spacing: (attributes org.gtk.Property.get=gtk_box_get_spacing 
org.gtk.Property.set=gtk_box_set_spacing)
+   *
+   * The amount of space between children.
+   */
   props[PROP_SPACING] =
     g_param_spec_int ("spacing",
                       P_("Spacing"),
@@ -262,6 +269,11 @@ gtk_box_class_init (GtkBoxClass *class)
                       0, G_MAXINT, 0,
                       GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkBox:homogeneous: (attributes org.gtk.Property.get=gtk_box_get_homogeneous 
org.gtk.Property.set=gtk_box_set_homogeneous)
+   *
+   * Whether the children should all be the same size.
+   */
   props[PROP_HOMOGENEOUS] =
     g_param_spec_boolean ("homogeneous",
                           P_("Homogeneous"),
@@ -269,6 +281,11 @@ gtk_box_class_init (GtkBoxClass *class)
                           FALSE,
                           GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkBox:baseline-position: (attributes org.gtk.Property.get=gtk_box_get_baseline_position 
org.gtk.Property.set=gtk_box_set_baseline_position)
+   *
+   * The position of the baseline aligned widgets if extra space is available.
+   */
   props[PROP_BASELINE_POSITION] =
     g_param_spec_enum ("baseline-position",
                        P_("Baseline position"),
@@ -319,10 +336,10 @@ gtk_box_buildable_iface_init (GtkBuildableIface *iface)
  * @orientation: the box’s orientation
  * @spacing: the number of pixels to place by default between children
  *
- * Creates a new #GtkBox.
+ * Creates a new `GtkBox`.
  *
- * Returns: a new #GtkBox.
- **/
+ * Returns: a new `GtkBox`.
+ */
 GtkWidget*
 gtk_box_new (GtkOrientation orientation,
              int            spacing)
@@ -334,13 +351,12 @@ gtk_box_new (GtkOrientation orientation,
 }
 
 /**
- * gtk_box_set_homogeneous:
- * @box: a #GtkBox
+ * gtk_box_set_homogeneous: (attributes org.gtk.Method.set_property=homogeneous)
+ * @box: a `GtkBox`
  * @homogeneous: a boolean value, %TRUE to create equal allotments,
  *   %FALSE for variable allotments
  *
- * Sets the #GtkBox:homogeneous property of @box, controlling
- * whether or not all children of @box are given equal space
+ * Sets whether or not all children of @box are given equal space
  * in the box.
  */
 void
@@ -362,14 +378,14 @@ gtk_box_set_homogeneous (GtkBox  *box,
 }
 
 /**
- * gtk_box_get_homogeneous:
- * @box: a #GtkBox
+ * gtk_box_get_homogeneous: (attributes org.gtk.Method.get_property=homogeneous)
+ * @box: a `GtkBox`
  *
  * Returns whether the box is homogeneous (all children are the
- * same size). See gtk_box_set_homogeneous().
+ * same size).
  *
  * Returns: %TRUE if the box is homogeneous.
- **/
+ */
 gboolean
 gtk_box_get_homogeneous (GtkBox *box)
 {
@@ -383,12 +399,11 @@ gtk_box_get_homogeneous (GtkBox *box)
 }
 
 /**
- * gtk_box_set_spacing:
- * @box: a #GtkBox
+ * gtk_box_set_spacing: (attributes org.gtk.Method.set_property=spacing)
+ * @box: a `GtkBox`
  * @spacing: the number of pixels to put between children
  *
- * Sets the #GtkBox:spacing property of @box, which is the
- * number of pixels to place between children of @box.
+ * Sets the number of pixels to place between children of @box.
  */
 void
 gtk_box_set_spacing (GtkBox *box,
@@ -407,13 +422,13 @@ gtk_box_set_spacing (GtkBox *box,
 }
 
 /**
- * gtk_box_get_spacing:
- * @box: a #GtkBox
+ * gtk_box_get_spacing: (attributes org.gtk.Method.get_property=spacing)
+ * @box: a `GtkBox`
  *
  * Gets the value set by gtk_box_set_spacing().
  *
  * Returns: spacing between children
- **/
+ */
 int
 gtk_box_get_spacing (GtkBox *box)
 {
@@ -427,15 +442,16 @@ gtk_box_get_spacing (GtkBox *box)
 }
 
 /**
- * gtk_box_set_baseline_position:
- * @box: a #GtkBox
- * @position: a #GtkBaselinePosition
- *
- * Sets the baseline position of a box. This affects
- * only horizontal boxes with at least one baseline aligned
- * child. If there is more vertical space available than requested,
- * and the baseline is not allocated by the parent then
- * @position is used to allocate the baseline wrt the
+ * gtk_box_set_baseline_position: (attributes org.gtk.Method.set_property=baseline-position)
+ * @box: a `GtkBox`
+ * @position: a `GtkBaselinePosition`
+ *
+ * Sets the baseline position of a box.
+ *
+ * This affects only horizontal boxes with at least one baseline
+ * aligned child. If there is more vertical space available than
+ * requested, and the baseline is not allocated by the parent then
+ * @position is used to allocate the baseline with respect to the
  * extra space available.
  */
 void
@@ -455,13 +471,13 @@ gtk_box_set_baseline_position (GtkBox             *box,
 }
 
 /**
- * gtk_box_get_baseline_position:
- * @box: a #GtkBox
+ * gtk_box_get_baseline_position: (attributes org.gtk.Method.get_property=baseline-position)
+ * @box: a `GtkBox`
  *
  * Gets the value set by gtk_box_set_baseline_position().
  *
  * Returns: the baseline position
- **/
+ */
 GtkBaselinePosition
 gtk_box_get_baseline_position (GtkBox *box)
 {
@@ -476,13 +492,14 @@ gtk_box_get_baseline_position (GtkBox *box)
 
 /**
  * gtk_box_insert_child_after:
- * @box: a #GtkBox
- * @child: the #GtkWidget to insert
+ * @box: a `GtkBox`
+ * @child: the `GtkWidget` to insert
  * @sibling: (nullable): the sibling after which to insert @child
  *
  * Inserts @child in the position after @sibling in the list
- * of @box children. If @sibling is %NULL, insert @child at
- * the first position.
+ * of @box children.
+ *
+ * If @sibling is %NULL, insert @child at the first position.
  */
 void
 gtk_box_insert_child_after (GtkBox    *box,
@@ -511,13 +528,14 @@ gtk_box_insert_child_after (GtkBox    *box,
 
 /**
  * gtk_box_reorder_child_after:
- * @box: a #GtkBox
- * @child: the #GtkWidget to move, must be a child of @box
+ * @box: a `GtkBox`
+ * @child: the `GtkWidget` to move, must be a child of @box
  * @sibling: (nullable): the sibling to move @child after, or %NULL
  *
  * Moves @child to the position after @sibling in the list
- * of @box children. If @sibling is %NULL, move @child to
- * the first position.
+ * of @box children.
+ *
+ * If @sibling is %NULL, move @child to the first position.
  */
 void
 gtk_box_reorder_child_after (GtkBox    *box,
@@ -546,8 +564,8 @@ gtk_box_reorder_child_after (GtkBox    *box,
 
 /**
  * gtk_box_append:
- * @box: a #GtkBox
- * @child: the #GtkWidget to append
+ * @box: a `GtkBox`
+ * @child: the `GtkWidget` to append
  *
  * Adds @child as the last child to @box.
  */
@@ -564,8 +582,8 @@ gtk_box_append (GtkBox    *box,
 
 /**
  * gtk_box_prepend:
- * @box: a #GtkBox
- * @child: the #GtkWidget to prepend
+ * @box: a `GtkBox`
+ * @child: the `GtkWidget` to prepend
  *
  * Adds @child as the first child to @box.
  */
@@ -582,12 +600,14 @@ gtk_box_prepend (GtkBox    *box,
 
 /**
  * gtk_box_remove:
- * @box: a #GtkBox
+ * @box: a `GtkBox`
  * @child: the child to remove
  *
- * Removes a child widget from @box, after it has been
- * added with gtk_box_append(), gtk_box_prepend(), or
- * gtk_box_insert_child_after().
+ * Removes a child widget from @box.
+ *
+ * The child must have been added before with
+ * [method Gtk Box.append], [method Gtk Box.prepend], or
+ * [method Gtk Box.insert_child_after].
  */
 void
 gtk_box_remove (GtkBox    *box,