[gtk/ebassi/gidocgen: 102/501] togglebutton: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit bf35460578eb5db5de6eaf0e2920c0259f35e90e
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 21 11:16:19 2021 -0500

    togglebutton: Convert docs
    
    Change link syntax, add an example image, generally clean things up.

 gtk/gtktogglebutton.c | 122 ++++++++++++++++++++++++++++++--------------------
 1 file changed, 74 insertions(+), 48 deletions(-)
---
diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c
index 88eea5a8cf..3320ef0005 100644
--- a/gtk/gtktogglebutton.c
+++ b/gtk/gtktogglebutton.c
@@ -36,39 +36,48 @@
 #include "gtkprivate.h"
 
 /**
- * SECTION:gtktogglebutton
- * @Short_description: Create buttons which retain their state
- * @Title: GtkToggleButton
- * @See_also: #GtkButton, #GtkCheckButton
+ * GtkToggleButton:
  *
- * A #GtkToggleButton is a #GtkButton which will remain “pressed-in” when
- * clicked. Clicking again will cause the toggle button to return to its
- * normal state.
+ * A `GtkToggleButton` is a button which remains “pressed-in” when
+ * clicked.
  *
- * A toggle button is created by calling either gtk_toggle_button_new() or
- * gtk_toggle_button_new_with_label(). If using the former, it is advisable to
- * pack a widget, (such as a #GtkLabel and/or a #GtkImage), into the toggle
- * button’s container. (See #GtkButton for more information).
+ * Clicking again will cause the toggle button to return to its normal state.
  *
- * The state of a #GtkToggleButton can be set specifically using
- * gtk_toggle_button_set_active(), and retrieved using
- * gtk_toggle_button_get_active().
+ * A toggle button is created by calling either [ctor Gtk ToggleButton new] or
+ * [ctor@Gtk.ToggleButton.new_with_label]. If using the former, it is advisable
+ * to pack a widget, (such as a `GtkLabel` and/or a `GtkImage`), into the toggle
+ * button’s container. (See [class@Gtk.Button] for more information).
  *
- * To simply switch the state of a toggle button, use gtk_toggle_button_toggled().
+ * The state of a `GtkToggleButton` can be set specifically using
+ * [method@Gtk.ToggleButton.set_active], and retrieved using
+ * [method@Gtk.ToggleButton.get_active].
+ *
+ * To simply switch the state of a toggle button, use
+ * [method@Gtk.ToggleButton.toggled].
+ *
+ * # Grouping
+ *
+ * Toggle buttons can be grouped together, to form mutually exclusive
+ * groups - only one of the buttons can be toggled at a time, and toggling
+ * another one will switch the currently toggled one off.
+ *
+ * To add a `GtkToggleButton` to a group, use [method@Gtk.ToggleButton.set_group].
  *
  * # CSS nodes
  *
- * GtkToggleButton has a single CSS node with name button. To differentiate
- * it from a plain #GtkButton, it gets the .toggle style class.
+ * `GtkToggleButton` has a single CSS node with name button. To differentiate
+ * it from a plain `GtkButton`, it gets the .toggle style class.
  *
- * ## Creating two #GtkToggleButton widgets.
+ * ## Creating two `GtkToggleButton` widgets.
  *
- * |[<!-- language="C" -->
- * static void output_state (GtkToggleButton *source, gpointer user_data) {
+ * ```c
+ * static void output_state (GtkToggleButton *source, gpointer user_data)
+ * {
  *   printf ("Active: %d\n", gtk_toggle_button_get_active (source));
  * }
  *
- * void make_toggles (void) {
+ * void make_toggles (void)
+ * {
  *   GtkWidget *window, *toggle1, *toggle2;
  *   GtkWidget *box;
  *   const char *text;
@@ -94,7 +103,7 @@
  *   gtk_window_set_child (GTK_WINDOW (window), box);
  *   gtk_widget_show (window);
  * }
- * ]|
+ * ```
  */
 
 typedef struct _GtkToggleButtonPrivate       GtkToggleButtonPrivate;
@@ -254,6 +263,11 @@ gtk_toggle_button_class_init (GtkToggleButtonClass *class)
 
   class->toggled = NULL;
 
+  /**
+   * GtkToggleButton:active:
+   *
+   * If the toggle button should be pressed in.
+   */
   toggle_button_props[PROP_ACTIVE] =
       g_param_spec_boolean ("active",
                             P_("Active"),
@@ -261,6 +275,11 @@ gtk_toggle_button_class_init (GtkToggleButtonClass *class)
                             FALSE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkToggleButton:group:
+   *
+   * The toggle button whose group this widget belongs to.
+   */
   toggle_button_props[PROP_GROUP] =
       g_param_spec_object ("group",
                            P_("Group"),
@@ -274,8 +293,7 @@ gtk_toggle_button_class_init (GtkToggleButtonClass *class)
    * GtkToggleButton::toggled:
    * @togglebutton: the object which received the signal.
    *
-   * Should be connected if you wish to perform an action whenever the
-   * #GtkToggleButton's state is changed.
+   * Emitted whenever the `GtkToggleButton`'s state is changed.
    */
   toggle_button_signals[TOGGLED] =
     g_signal_new (I_("toggled"),
@@ -303,7 +321,9 @@ gtk_toggle_button_init (GtkToggleButton *toggle_button)
 /**
  * gtk_toggle_button_new:
  *
- * Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new().
+ * Creates a new toggle button.
+ *
+ * A widget should be packed into the button, as in [ctor Gtk Button new].
  *
  * Returns: a new toggle button.
  */
@@ -332,11 +352,12 @@ gtk_toggle_button_new_with_label (const char *label)
  * @label: the text of the button, with an underscore in front of the
  *         mnemonic character
  *
- * Creates a new #GtkToggleButton containing a label. The label
- * will be created using gtk_label_new_with_mnemonic(), so underscores
- * in @label indicate the mnemonic for the button.
+ * Creates a new `GtkToggleButton` containing a label.
  *
- * Returns: a new #GtkToggleButton
+ * The label will be created using [ctor@Gtk.Label.new_with_mnemonic],
+ * so underscores in @label indicate the mnemonic for the button.
+ *
+ * Returns: a new `GtkToggleButton`
  */
 GtkWidget *
 gtk_toggle_button_new_with_mnemonic (const char *label)
@@ -349,14 +370,16 @@ gtk_toggle_button_new_with_mnemonic (const char *label)
 
 /**
  * gtk_toggle_button_set_active:
- * @toggle_button: a #GtkToggleButton.
+ * @toggle_button: a `GtkToggleButton`.
  * @is_active: %TRUE or %FALSE.
  *
- * Sets the status of the toggle button. Set to %TRUE if you want the
- * GtkToggleButton to be “pressed in”, and %FALSE to raise it.
+ * Sets the status of the toggle button.
+ *
+ * Set to %TRUE if you want the `GtkToggleButton` to be “pressed in”,
+ * and %FALSE to raise it.
  *
  * If the status of the button changes, this action causes the
- * #GtkToggleButton::toggled signal to be emitted.
+ * [signal@GtkToggleButton::toggled] signal to be emitted.
  */
 void
 gtk_toggle_button_set_active (GtkToggleButton *toggle_button,
@@ -404,12 +427,14 @@ gtk_toggle_button_set_active (GtkToggleButton *toggle_button,
 
 /**
  * gtk_toggle_button_get_active:
- * @toggle_button: a #GtkToggleButton.
+ * @toggle_button: a `GtkToggleButton`.
  *
- * Queries a #GtkToggleButton and returns its current state. Returns %TRUE if
- * the toggle button is pressed in and %FALSE if it is raised.
+ * Queries a `GtkToggleButton` and returns its current state.
  *
- * Returns: a #gboolean value.
+ * Returns %TRUE if the toggle button is pressed in and %FALSE
+ * if it is raised.
+ *
+ * Returns: whether the button is pressed
  */
 gboolean
 gtk_toggle_button_get_active (GtkToggleButton *toggle_button)
@@ -423,11 +448,11 @@ gtk_toggle_button_get_active (GtkToggleButton *toggle_button)
 
 /**
  * gtk_toggle_button_toggled:
- * @toggle_button: a #GtkToggleButton.
+ * @toggle_button: a `GtkToggleButton`.
+ *
+ * Emits the ::toggled signal on the `GtkToggleButton`.
  *
- * Emits the #GtkToggleButton::toggled signal on the
- * #GtkToggleButton. There is no good reason for an
- * application ever to call this function.
+ * There is no good reason for an application ever to call this function.
  */
 void
 gtk_toggle_button_toggled (GtkToggleButton *toggle_button)
@@ -439,18 +464,19 @@ gtk_toggle_button_toggled (GtkToggleButton *toggle_button)
 
 /**
  * gtk_toggle_button_set_group:
- * @toggle_button: a #GtkToggleButton
- * @group: (nullable) (transfer none): another #GtkToggleButton to
+ * @toggle_button: a `GtkToggleButton`
+ * @group: (nullable) (transfer none): another `GtkToggleButton` to
  *   form a group with
  *
- * Adds @self to the group of @group. In a group of multiple toggle buttons,
- * only one button can be active at a time.
+ * Adds @self to the group of @group.
  *
- * Note that the same effect can be achieved via the #GtkActionable
- * api, by using the same action with parameter type and state type 's'
+ * In a group of multiple toggle buttons, only one button can be active
+ * at a time.
+ *
+ * Note that the same effect can be achieved via the [interface@Gtk.Actionable]
+ * API, by using the same action with parameter type and state type 's'
  * for all buttons in the group, and giving each button its own target
  * value.
-
  */
 void
 gtk_toggle_button_set_group (GtkToggleButton *toggle_button,