[gtk/ebassi/gidocgen: 465/478] sizegroup: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit 201a50290f48c2996f0b0abeb1184263ce34f179
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 1 22:53:47 2021 -0500

    sizegroup: Convert docs

 gtk/gtksizegroup.c | 124 ++++++++++++++++++++++++++++-------------------------
 1 file changed, 65 insertions(+), 59 deletions(-)
---
diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c
index dbb34535b5..4d8e760748 100644
--- a/gtk/gtksizegroup.c
+++ b/gtk/gtksizegroup.c
@@ -30,30 +30,26 @@
 
 
 /**
- * SECTION:gtksizegroup
- * @Short_description: Grouping widgets so they request the same size
- * @Title: GtkSizeGroup
+ * GtkSizeGroup
  *
- * #GtkSizeGroup provides a mechanism for grouping a number of widgets
- * together so they all request the same amount of space.  This is
- * typically useful when you want a column of widgets to have the same
- * size, but you can’t use a #GtkGrid widget.
+ * `GtkSizeGroup` groups widgets together so they all request the same size.
  *
- * In detail, the size requested for each widget in a #GtkSizeGroup is
+ * This is typically useful when you want a column of widgets to have the
+ * same size, but you can’t use a `GtkGrid`.
+ *
+ * In detail, the size requested for each widget in a `GtkSizeGroup` is
  * the maximum of the sizes that would have been requested for each
  * widget in the size group if they were not in the size group. The mode
- * of the size group (see gtk_size_group_set_mode()) determines whether
+ * of the size group (see [method@Gtk.SizeGroup.set_mode]) determines whether
  * this applies to the horizontal size, the vertical size, or both sizes.
  *
  * Note that size groups only affect the amount of space requested, not
  * the size that the widgets finally receive. If you want the widgets in
- * a #GtkSizeGroup to actually be the same size, you need to pack them in
- * such a way that they get the size they request and not more. For
- * example, if you are packing your widgets into a table, you would not
- * include the %GTK_FILL flag.
+ * a `GtkSizeGroup` to actually be the same size, you need to pack them in
+ * such a way that they get the size they request and not more.
  *
- * #GtkSizeGroup objects are referenced by each widget in the size group,
- * so once you have added all widgets to a #GtkSizeGroup, you can drop
+ * `GtkSizeGroup` objects are referenced by each widget in the size group,
+ * so once you have added all widgets to a `GtkSizeGroup`, you can drop
  * the initial reference to the size group with g_object_unref(). If the
  * widgets in the size group are subsequently destroyed, then they will
  * be removed from the size group and drop their references on the size
@@ -77,9 +73,10 @@
  * widgets in the group. The same is of course true when horizontally grouping
  * width for height widgets.
  *
- * Widgets that trade height-for-width should set a reasonably large minimum width
- * by way of #GtkLabel:width-chars for instance. Widgets with static sizes as well
- * as widgets that grow (such as ellipsizing text) need no such considerations.
+ * Widgets that trade height-for-width should set a reasonably large minimum
+ * width by way of [property@Gtk.Label:width-chars] for instance. Widgets with
+ * static sizes as well as widgets that grow (such as ellipsizing text) need no
+ * such considerations.
  *
  * # GtkSizeGroup as GtkBuildable
  *
@@ -89,8 +86,8 @@
  * that may contain multiple <widget> elements, one for each member of the
  * size group. The ”name” attribute gives the id of the widget.
  *
- * An example of a UI definition fragment with GtkSizeGroup:
- * |[
+ * An example of a UI definition fragment with `GtkSizeGroup`:
+ * ```xml
  * <object class="GtkSizeGroup">
  *   <property name="mode">horizontal</property>
  *   <widgets>
@@ -98,7 +95,7 @@
  *     <widget name="radio2"/>
  *   </widgets>
  * </object>
- * ]|
+ * ```
  */
 
 typedef struct _GtkSizeGroupClass GtkSizeGroupClass;
@@ -219,7 +216,12 @@ gtk_size_group_class_init (GtkSizeGroupClass *klass)
 
   gobject_class->set_property = gtk_size_group_set_property;
   gobject_class->get_property = gtk_size_group_get_property;
-  
+
+  /**
+   * GtkSizeGroup:mode: (attributes org.gtk.Property.get=gtk_size_group_get_mode 
org.gtk.Property.set=gtk_size_group_set_mode)
+   *
+   * The direction in which the size group affects requested sizes.
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_MODE,
                                    g_param_spec_enum ("mode",
@@ -291,11 +293,11 @@ gtk_size_group_get_property (GObject      *object,
 /**
  * gtk_size_group_new:
  * @mode: the mode for the new size group.
- * 
- * Create a new #GtkSizeGroup.
- 
- * Returns: a newly created #GtkSizeGroup
- **/
+ *
+ * Create a new `GtkSizeGroup`.
+ *
+ * Returns: a newly created `GtkSizeGroup`
+ */
 GtkSizeGroup *
 gtk_size_group_new (GtkSizeGroupMode mode)
 {
@@ -308,17 +310,18 @@ gtk_size_group_new (GtkSizeGroupMode mode)
 }
 
 /**
- * gtk_size_group_set_mode:
- * @size_group: a #GtkSizeGroup
+ * gtk_size_group_set_mode: (attributes org.gtk.Method.set_property=mode)
+ * @size_group: a `GtkSizeGroup`
  * @mode: the mode to set for the size group.
- * 
- * Sets the #GtkSizeGroupMode of the size group. The mode of the size
- * group determines whether the widgets in the size group should
- * all have the same horizontal requisition (%GTK_SIZE_GROUP_HORIZONTAL)
- * all have the same vertical requisition (%GTK_SIZE_GROUP_VERTICAL),
- * or should all have the same requisition in both directions
- * (%GTK_SIZE_GROUP_BOTH).
- **/
+ *
+ * Sets the `GtkSizeGroupMode` of the size group.
+ *
+ * The mode of the size group determines whether the widgets in the
+ * size group should all have the same horizontal requisition
+ * (%GTK_SIZE_GROUP_HORIZONTAL) all have the same vertical requisition
+ * (%GTK_SIZE_GROUP_VERTICAL), or should all have the same requisition
+ * in both directions (%GTK_SIZE_GROUP_BOTH).
+ */
 void
 gtk_size_group_set_mode (GtkSizeGroup     *size_group,
                         GtkSizeGroupMode  mode)
@@ -340,13 +343,13 @@ gtk_size_group_set_mode (GtkSizeGroup     *size_group,
 }
 
 /**
- * gtk_size_group_get_mode:
- * @size_group: a #GtkSizeGroup
- * 
- * Gets the current mode of the size group. See gtk_size_group_set_mode().
- * 
+ * gtk_size_group_get_mode: (attributes org.gtk.Method.get_property=mode)
+ * @size_group: a `GtkSizeGroup`
+ *
+ * Gets the current mode of the size group.
+ *
  * Returns: the current mode of the size group.
- **/
+ */
 GtkSizeGroupMode
 gtk_size_group_get_mode (GtkSizeGroup *size_group)
 {
@@ -359,17 +362,20 @@ gtk_size_group_get_mode (GtkSizeGroup *size_group)
 
 /**
  * gtk_size_group_add_widget:
- * @size_group: a #GtkSizeGroup
- * @widget: the #GtkWidget to add
- * 
- * Adds a widget to a #GtkSizeGroup. In the future, the requisition
+ * @size_group: a `GtkSizeGroup`
+ * @widget: the `GtkWidget` to add
+ *
+ * Adds a widget to a `GtkSizeGroup`.
+ *
+ * In the future, the requisition
  * of the widget will be determined as the maximum of its requisition
  * and the requisition of the other widgets in the size group.
  * Whether this applies horizontally, vertically, or in both directions
- * depends on the mode of the size group. See gtk_size_group_set_mode().
+ * depends on the mode of the size group.
+ * See [method@Gtk.SizeGroup.set_mode].
  *
- * When the widget is destroyed or no longer referenced elsewhere, it will 
- * be removed from the size group.
+ * When the widget is destroyed or no longer referenced elsewhere, it
+ * will be removed from the size group.
  */
 void
 gtk_size_group_add_widget (GtkSizeGroup *size_group,
@@ -397,11 +403,11 @@ gtk_size_group_add_widget (GtkSizeGroup *size_group,
 
 /**
  * gtk_size_group_remove_widget:
- * @size_group: a #GtkSizeGroup
- * @widget: the #GtkWidget to remove
- * 
- * Removes a widget from a #GtkSizeGroup.
- **/
+ * @size_group: a `GtkSizeGroup`
+ * @widget: the `GtkWidget` to remove
+ *
+ * Removes a widget from a `GtkSizeGroup`.
+ */
 void
 gtk_size_group_remove_widget (GtkSizeGroup *size_group,
                              GtkWidget    *widget)
@@ -424,13 +430,13 @@ gtk_size_group_remove_widget (GtkSizeGroup *size_group,
 
 /**
  * gtk_size_group_get_widgets:
- * @size_group: a #GtkSizeGroup
- * 
+ * @size_group: a `GtkSizeGroup`
+ *
  * Returns the list of widgets associated with @size_group.
  *
- * Returns:  (element-type GtkWidget) (transfer none): a #GSList of
+ * Returns:  (element-type GtkWidget) (transfer none): a `GSList` of
  *   widgets. The list is owned by GTK and should not be modified.
- **/
+ */
 GSList *
 gtk_size_group_get_widgets (GtkSizeGroup *size_group)
 {