[gtk/ebassi/gidocgen: 28/465] infobar: Convert docs

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/gidocgen: 28/465] infobar: Convert docs
Date: Mon, 8 Mar 2021 22:25:59 +0000 (UTC)

commit c5e03a9723fc6e46588a20d98e66b575c73fdd0a
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 19 16:01:07 2021 -0500

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

 gtk/gtkinfobar.c | 182 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 102 insertions(+), 80 deletions(-)
---
diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c
index 608c6b77ff..8213acf5ce 100644
--- a/gtk/gtkinfobar.c
+++ b/gtk/gtkinfobar.c
@@ -53,27 +53,30 @@
  * @include: gtk/gtk.h
  * @see_also: #GtkStatusbar, #GtkMessageDialog
  *
- * #GtkInfoBar is a widget that can be used to show messages to
- * the user without showing a dialog. It is often temporarily shown
- * at the top or bottom of a document. In contrast to #GtkDialog, which
- * has an action area at the bottom, #GtkInfoBar has an action area
- * at the side.
+ * `GtkInfoBar` is a widget that can be used to show messages to
+ * the user without showing a dialog.
  *
- * The API of #GtkInfoBar is very similar to #GtkDialog, allowing you
- * to add buttons to the action area with gtk_info_bar_add_button() or
- * gtk_info_bar_new_with_buttons(). The sensitivity of action widgets
- * can be controlled with gtk_info_bar_set_response_sensitive().
+ * ![An example GtkInfoBar](infobar.png)
  *
- * To add widgets to the main content area of a #GtkInfoBar, use
- * gtk_info_bar_add_child().
+ * It is often temporarily shown at the top or bottom of a document.
+ * In contrast to [class@Gtk.Dialog], which has an action area at the
+ * bottom, `GtkInfoBar` has an action area at the side.
  *
- * Similar to #GtkMessageDialog, the contents of a #GtkInfoBar can by
- * classified as error message, warning, informational message, etc,
- * by using gtk_info_bar_set_message_type(). GTK may use the message type
- * to determine how the message is displayed.
+ * The API of `GtkInfoBar` is very similar to `GtkDialog`, allowing you
+ * to add buttons to the action area with [method@Gtk.InfoBar.add_button]
+ * or [ctor@Gtk.InfoBar.new_with_buttons]. The sensitivity of action widgets
+ * can be controlled with [method@Gtk.InfoBar.set_response_sensitive].
  *
- * A simple example for using a #GtkInfoBar:
- * |[<!-- language="C" -->
+ * To add widgets to the main content area of a `GtkInfoBar`, use
+ * [method@Gtk.InfoBar.add_child].
+ *
+ * Similar to [class@Gtk.MessageDialog], the contents of a `GtkInfoBar`
+ * can by classified as error message, warning, informational message, etc,
+ * by using [method@Gtk.InfoBar.set_message_type]. GTK may use the message
+ * type to determine how the message is displayed.
+ *
+ * A simple example for using a `GtkInfoBar`:
+ * ```c
  * GtkWidget *message_label;
  * GtkWidget *widget;
  * GtkWidget *grid;
@@ -103,22 +106,22 @@
  * gtk_label_set_text (GTK_LABEL (message_label), "An error occurred!");
  * gtk_info_bar_set_message_type (bar, GTK_MESSAGE_ERROR);
  * gtk_widget_show (bar);
- * ]|
+ * ```
  *
  * # GtkInfoBar as GtkBuildable
  *
- * The GtkInfoBar implementation of the GtkBuildable interface exposes
+ * The `GtkInfoBar` implementation of the `GtkBuildable` interface exposes
  * the content area and action area as internal children with the names
  * “content_area” and “action_area”.
  *
- * GtkInfoBar supports a custom <action-widgets> element, which can contain
+ * `GtkInfoBar` supports a custom <action-widgets> element, which can contain
  * multiple <action-widget> elements. The “response” attribute specifies a
  * numeric response, and the content of the element is the id of widget
  * (which should be a child of the dialogs @action_area).
  *
  * # CSS nodes
  *
- * GtkInfoBar has a single CSS node with name infobar. The node may get
+ * `GtkInfoBar` has a single CSS node with name infobar. The node may get
  * one of the style classes .info, .warning, .error or .question, depending
  * on the message type.
  * If the info bar shows a close button, that button will have the .close
@@ -372,6 +375,11 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass)
                           FALSE,
                           GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkInfoBar:revealed:
+   *
+   * Whether the info bar shows its contents.
+   */
   props[PROP_REVEALED] =
     g_param_spec_boolean ("revealed",
                           P_("Reveal"),
@@ -386,9 +394,11 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass)
    * @info_bar: the object on which the signal is emitted
    * @response_id: the response ID
    *
-   * Emitted when an action widget is clicked or the application programmer
-   * calls gtk_info_bar_response(). The @response_id depends on which action
-   * widget was clicked.
+   * Emitted when an action widget is clicked.
+   *
+   * The signal is also emitted when the application programmer
+   * calls [method@Gtk.InfoBar.response]. The @response_id depends
+   * on which action widget was clicked.
    */
   signals[RESPONSE] = g_signal_new (I_("response"),
                                     G_OBJECT_CLASS_TYPE (klass),
@@ -402,10 +412,9 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass)
   /**
    * GtkInfoBar::close:
    *
-   * The ::close signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user uses a keybinding to dismiss
-   * the info bar.
+   * Gets emitted when the user uses a keybinding to dismiss the info bar.
+   *
+   * The ::close signal is a [keybinding signal](class.SignalAction.html).
    *
    * The default binding for this signal is the Escape key.
    */
@@ -523,14 +532,16 @@ action_widget_activated (GtkWidget  *widget,
 
 /**
  * gtk_info_bar_add_action_widget:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @child: an activatable widget
  * @response_id: response ID for @child
  *
- * Add an activatable widget to the action area of a #GtkInfoBar,
- * connecting a signal handler that will emit the #GtkInfoBar::response
- * signal on the message area when the widget is activated. The widget
- * is appended to the end of the message areas action area.
+ * Add an activatable widget to the action area of a `GtkInfoBar`.
+ *
+ * This also connects a signal handler that will emit the
+ * [signal@Gtk.InfoBar::response] signal on the message area
+ * when the widget is activated. The widget is appended to the
+ * end of the message areas action area.
  */
 void
 gtk_info_bar_add_action_widget (GtkInfoBar *info_bar,
@@ -569,12 +580,13 @@ gtk_info_bar_add_action_widget (GtkInfoBar *info_bar,
 
 /**
  * gtk_info_bar_remove_action_widget:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @widget: an action widget to remove
  *
- * Removes a widget from the action area of @info_bar, after
- * it been put there by a call to gtk_info_bar_add_action_widget()
- * or gtk_info_bar_add_button().
+ * Removes a widget from the action area of @info_bar.
+ *
+ * The widget must have been put there by a call to
+ * [method@Gtk.InfoBar.add_action_widget] or [method@Gtk.InfoBar.add_button].
  */
 void
 gtk_info_bar_remove_action_widget (GtkInfoBar *info_bar,
@@ -591,17 +603,18 @@ gtk_info_bar_remove_action_widget (GtkInfoBar *info_bar,
 
 /**
  * gtk_info_bar_add_button:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @button_text: text of button
  * @response_id: response ID for the button
  *
- * Adds a button with the given text and sets things up so that
- * clicking the button will emit the “response” signal with the given
- * response_id. The button is appended to the end of the info bars's
- * action area. The button widget is returned, but usually you don't
- * need it.
+ * Adds a button with the given text.
  *
- * Returns: (transfer none) (type Gtk.Button): the #GtkButton widget
+ * Clicking the button will emit the [signal@Gtk.InfoBar::response]
+ * signal with the given response_id. The button is appended to the
+ * end of the info bars's action area. The button widget is returned,
+ * but usually you don't need it.
+ *
+ * Returns: (transfer none) (type Gtk.Button): the `GtkButton` widget
  * that was added
  */
 GtkWidget*
@@ -654,14 +667,16 @@ add_buttons_valist (GtkInfoBar  *info_bar,
 
 /**
  * gtk_info_bar_add_buttons:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @first_button_text: button text
  * @...: response ID for first button, then more text-response_id pairs,
  *     ending with %NULL
  *
- * Adds more buttons, same as calling gtk_info_bar_add_button()
+ * Adds multiple buttons.
+ *
+ * This is the same as calling [method@Gtk.InfoBar.add_button]
  * repeatedly. The variable argument list should be %NULL-terminated
- * as with gtk_info_bar_new_with_buttons(). Each button must have both
+ * as with [ctor@Gtk.InfoBar.new_with_buttons]. Each button must have both
  * text and response ID.
  */
 void
@@ -679,9 +694,9 @@ gtk_info_bar_add_buttons (GtkInfoBar  *info_bar,
 /**
  * gtk_info_bar_new:
  *
- * Creates a new #GtkInfoBar object.
+ * Creates a new `GtkInfoBar` object.
  *
- * Returns: a new #GtkInfoBar object
+ * Returns: a new `GtkInfoBar` object
  */
 GtkWidget *
 gtk_info_bar_new (void)
@@ -695,14 +710,16 @@ gtk_info_bar_new (void)
  * @...: response ID for first button, then additional buttons, ending
  *    with %NULL
  *
- * Creates a new #GtkInfoBar with buttons. Button text/response ID
- * pairs should be listed, with a %NULL pointer ending the list.
- * A response ID can be any positive number,
- * or one of the values in the #GtkResponseType enumeration. If the
+ * Creates a new `GtkInfoBar` with buttons.
+ *
+ * Button text/response ID pairs should be listed, with a %NULL pointer
+ * ending the list. A response ID can be any positive number,
+ * or one of the values in the `GtkResponseType` enumeration. If the
  * user clicks one of these dialog buttons, GtkInfoBar will emit
- * the “response” signal with the corresponding response ID.
+ * the [signal@Gtk.InfoBar::response] signal with the corresponding
+ * response ID.
  *
- * Returns: a new #GtkInfoBar
+ * Returns: a new `GtkInfoBar`
  */
 GtkWidget*
 gtk_info_bar_new_with_buttons (const char *first_button_text,
@@ -736,13 +753,15 @@ update_default_response (GtkInfoBar *info_bar,
 
 /**
  * gtk_info_bar_set_response_sensitive:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @response_id: a response ID
  * @setting: TRUE for sensitive
  *
- * Calls gtk_widget_set_sensitive (widget, setting) for each
- * widget in the info bars’s action area with the given response_id.
- * A convenient way to sensitize/desensitize dialog buttons.
+ * Sets the sensitivity of action widgets for @response_id.
+ *
+ * Calls `gtk_widget_set_sensitive (widget, setting)` for each
+ * widget in the info bars’s action area with the given @response_id.
+ * A convenient way to sensitize/desensitize buttons.
  */
 void
 gtk_info_bar_set_response_sensitive (GtkInfoBar *info_bar,
@@ -769,15 +788,16 @@ gtk_info_bar_set_response_sensitive (GtkInfoBar *info_bar,
 
 /**
  * gtk_info_bar_set_default_response:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @response_id: a response ID
  *
  * Sets the last widget in the info bar’s action area with
  * the given response_id as the default widget for the dialog.
+ *
  * Pressing “Enter” normally activates the default widget.
  *
  * Note that this function currently requires @info_bar to
- * be added to a widget hierarchy. 
+ * be added to a widget hierarchy.
  */
 void
 gtk_info_bar_set_default_response (GtkInfoBar *info_bar,
@@ -810,7 +830,7 @@ gtk_info_bar_set_default_response (GtkInfoBar *info_bar,
 
 /**
  * gtk_info_bar_response:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @response_id: a response ID
  *
  * Emits the “response” signal with the given @response_id.
@@ -1054,7 +1074,7 @@ gtk_info_bar_buildable_add_child (GtkBuildable *buildable,
 
 /**
  * gtk_info_bar_set_message_type:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @message_type: a #GtkMessageType
  *
  * Sets the message type of the message area.
@@ -1093,7 +1113,7 @@ gtk_info_bar_set_message_type (GtkInfoBar     *info_bar,
 
 /**
  * gtk_info_bar_get_message_type:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  *
  * Returns the message type of the message area.
  *
@@ -1110,11 +1130,12 @@ gtk_info_bar_get_message_type (GtkInfoBar *info_bar)
 
 /**
  * gtk_info_bar_set_show_close_button:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @setting: %TRUE to include a close button
  *
- * If true, a standard close button is shown. When clicked it emits
- * the response %GTK_RESPONSE_CLOSE.
+ * If true, a standard close button is shown.
+ *
+ * When clicked it emits the response %GTK_RESPONSE_CLOSE.
  */
 void
 gtk_info_bar_set_show_close_button (GtkInfoBar *info_bar,
@@ -1131,7 +1152,7 @@ gtk_info_bar_set_show_close_button (GtkInfoBar *info_bar,
 
 /**
  * gtk_info_bar_get_show_close_button:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  *
  * Returns whether the widget will display a standard close button.
  *
@@ -1147,14 +1168,17 @@ gtk_info_bar_get_show_close_button (GtkInfoBar *info_bar)
 
 /**
  * gtk_info_bar_set_revealed:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @revealed: The new value of the property
  *
- * Sets the #GtkInfoBar:revealed property to @revealed. Changing this will make
- * @info_bar reveal (%TRUE) or conceal (%FALSE) itself via a sliding transition.
+ * Sets whether the `GtkInfoBar` is revealed.
  *
- * Note: this does not show or hide @info_bar in the #GtkWidget:visible sense,
- * so revealing has no effect if #GtkWidget:visible is %FALSE.
+ * Changing this will make @info_bar reveal or conceal
+ * itself via a sliding transition.
+ *
+ * Note: this does not show or hide @info_bar in the
+ * [property@Gtk.Widget:visible] sense, so revealing has no effect
+ * if [property@Gtk.Widget:visible] is %FALSE.
  */
 void
 gtk_info_bar_set_revealed (GtkInfoBar *info_bar,
@@ -1171,11 +1195,11 @@ gtk_info_bar_set_revealed (GtkInfoBar *info_bar,
 
 /**
  * gtk_info_bar_get_revealed:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  *
  * Returns whether the info bar is currently revealed.
  *
- * Returns: the current value of the #GtkInfoBar:revealed property
+ * Returns: the current value of the [property@Gtk.InfoBar:revealed] property
  */
 gboolean
 gtk_info_bar_get_revealed (GtkInfoBar *info_bar)
@@ -1187,7 +1211,7 @@ gtk_info_bar_get_revealed (GtkInfoBar *info_bar)
 
 /**
  * gtk_info_bar_add_child:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @widget: the child to be added
  *
  * Adds a widget to the content area of the info bar.
@@ -1204,11 +1228,10 @@ gtk_info_bar_add_child (GtkInfoBar *info_bar,
 
 /**
  * gtk_info_bar_remove_child:
- * @info_bar: a #GtkInfoBar
+ * @info_bar: a `GtkInfoBar`
  * @widget: a child that has been added to the content area
  *
- * Removes a widget from the content area of the info bar,
- * after it has been added with gtk_info_bar_add_child().
+ * Removes a widget from the content area of the info bar.
  */
 void
 gtk_info_bar_remove_child (GtkInfoBar *info_bar,
@@ -1219,4 +1242,3 @@ gtk_info_bar_remove_child (GtkInfoBar *info_bar,
 
   gtk_box_remove (GTK_BOX (info_bar->content_area), widget);
 }
-
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]