[gtk/ebassi/gidocgen: 60/500] progressbar: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit d58655b4ae17b21af26db49b406d200154f0ba01
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 19 15:43:33 2021 -0500

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

 gtk/gtkprogressbar.c | 168 +++++++++++++++++++++++++++++++--------------------
 1 file changed, 104 insertions(+), 64 deletions(-)
---
diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c
index 417c4538a0..2f7355c611 100644
--- a/gtk/gtkprogressbar.c
+++ b/gtk/gtkprogressbar.c
@@ -42,26 +42,29 @@
  * @Short_description: A widget which indicates progress visually
  * @Title: GtkProgressBar
  *
- * The #GtkProgressBar is typically used to display the progress of a long
- * running operation. It provides a visual clue that processing is underway.
- * The GtkProgressBar can be used in two different modes: percentage mode
- * and activity mode.
+ * `GtkProgressBar` is typically used to display the progress of a long
+ * running operation.
+ *
+ * It provides a visual clue that processing is underway. `GtkProgressBar`
+ * can be used in two different modes: percentage mode and activity mode.
+ *
+ * ![An example GtkProgressBar](progressbar.png)
  *
  * When an application can determine how much work needs to take place
  * (e.g. read a fixed number of bytes from a file) and can monitor its
- * progress, it can use the GtkProgressBar in percentage mode and the
+ * progress, it can use the `GtkProgressBar` in percentage mode and the
  * user sees a growing bar indicating the percentage of the work that
  * has been completed. In this mode, the application is required to call
- * gtk_progress_bar_set_fraction() periodically to update the progress bar.
+ * [method@Gtk.ProgressBar.set_fraction] periodically to update the progress bar.
  *
  * When an application has no accurate way of knowing the amount of work
- * to do, it can use the #GtkProgressBar in activity mode, which shows
+ * to do, it can use the `GtkProgressBar` in activity mode, which shows
  * activity by a block moving back and forth within the progress area. In
- * this mode, the application is required to call gtk_progress_bar_pulse()
+ * this mode, the application is required to call [method@Gtk.ProgressBar.pulse]
  * periodically to update the progress bar.
  *
  * There is quite a bit of flexibility provided to control the appearance
- * of the #GtkProgressBar. Functions are provided to control the orientation
+ * of the `GtkProgressBar`. Functions are provided to control the orientation
  * of the bar, optional text can be displayed along with the bar, and the
  * step size used in activity mode can be set.
  *
@@ -74,7 +77,7 @@
  *     ╰── progress[.pulse]
  * ]|
  *
- * GtkProgressBar has a main CSS node with name progressbar and subnodes with
+ * `GtkProgressBar` has a main CSS node with name progressbar and subnodes with
  * names text and trough, of which the latter has a subnode named progress. The
  * text subnode is only present if text is shown. The progress subnode has the
  * style class .pulse when in activity mode. It gets the style classes .left,
@@ -84,7 +87,7 @@
  *
  * # Accessibility
  *
- * GtkProgressBar uses the #GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role.
+ * `GtkProgressBar` uses the #GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role.
  */
 
 typedef struct _GtkProgressBarClass         GtkProgressBarClass;
@@ -177,6 +180,11 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
 
   g_object_class_override_property (gobject_class, PROP_ORIENTATION, "orientation");
 
+  /**
+   * GtkProgressBar:inverted:
+   *
+   * Invert the direction in which the progress bar grows.
+   */
   progress_props[PROP_INVERTED] =
       g_param_spec_boolean ("inverted",
                             P_("Inverted"),
@@ -184,6 +192,11 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
                             FALSE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkProgressBar:fraction:
+   *
+   * The fraction of total work that has been completed.
+   */
   progress_props[PROP_FRACTION] =
       g_param_spec_double ("fraction",
                            P_("Fraction"),
@@ -192,6 +205,11 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
                            0.0,
                            GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkProgressBar:pulse-step:
+   *
+   * The fraction of total progress to move the bounding block when pulsed.
+   */
   progress_props[PROP_PULSE_STEP] =
       g_param_spec_double ("pulse-step",
                            P_("Pulse Step"),
@@ -200,6 +218,11 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
                            0.1,
                            GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkProgressBar:text:
+   *
+   * Text to be displayed in the progress bar.
+   */
   progress_props[PROP_TEXT] =
       g_param_spec_string ("text",
                            P_("Text"),
@@ -211,14 +234,15 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
    * GtkProgressBar:show-text:
    *
    * Sets whether the progress bar will show a text in addition
-   * to the bar itself. The shown text is either the value of
-   * the #GtkProgressBar:text property or, if that is %NULL,
-   * the #GtkProgressBar:fraction value, as a percentage.
+   * to the bar itself.
    *
-   * To make a progress bar that is styled and sized suitably for
-   * showing text (even if the actual text is blank), set
-   * #GtkProgressBar:show-text to %TRUE and #GtkProgressBar:text
-   * to the empty string (not %NULL).
+   * The shown text is either the value of the [property@Gtk.ProgressBar:text]
+   * property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction]
+   * value, as a percentage.
+   *
+   * To make a progress bar that is styled and sized suitably for showing text
+   * (even if the actual text is blank), set [property@Gtk.ProgressBar:show-text]
+   * to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL).
    */
   progress_props[PROP_SHOW_TEXT] =
       g_param_spec_boolean ("show-text",
@@ -230,14 +254,15 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
   /**
    * GtkProgressBar:ellipsize:
    *
-   * The preferred place to ellipsize the string, if the progress bar does
-   * not have enough room to display the entire string, specified as a
-   * #PangoEllipsizeMode.
+   * The preferred place to ellipsize the string.
+   *
+   * The text will be ellipsized if the progress bar does not have enough room
+   * to display the entire string, specified as a `PangoEllipsizeMode`.
    *
    * Note that setting this property to a value other than
    * %PANGO_ELLIPSIZE_NONE has the side-effect that the progress bar requests
    * only enough space to display the ellipsis ("..."). Another means to set a
-   * progress bar's width is gtk_widget_set_size_request().
+   * progress bar's width is [method@Gtk.Widget.set_size_request].
    */
   progress_props[PROP_ELLIPSIZE] =
       g_param_spec_enum ("ellipsize",
@@ -548,9 +573,9 @@ gtk_progress_bar_get_property (GObject      *object,
 /**
  * gtk_progress_bar_new:
  *
- * Creates a new #GtkProgressBar.
+ * Creates a new `GtkProgressBar`.
  *
- * Returns: a #GtkProgressBar.
+ * Returns: a `GtkProgressBar`.
  */
 GtkWidget*
 gtk_progress_bar_new (void)
@@ -727,12 +752,13 @@ gtk_progress_bar_set_activity_mode (GtkProgressBar *pbar,
 
 /**
  * gtk_progress_bar_set_fraction:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  * @fraction: fraction of the task that’s been completed
  *
  * Causes the progress bar to “fill in” the given fraction
- * of the bar. The fraction should be between 0.0 and 1.0,
- * inclusive.
+ * of the bar.
+ *
+ * The fraction should be between 0.0 and 1.0, inclusive.
  */
 void
 gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
@@ -790,13 +816,14 @@ gtk_progress_bar_update_pulse (GtkProgressBar *pbar)
 
 /**
  * gtk_progress_bar_pulse:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  *
  * Indicates that some progress has been made, but you don’t know how much.
+ *
  * Causes the progress bar to enter “activity mode,” where a block
- * bounces back and forth. Each call to gtk_progress_bar_pulse()
+ * bounces back and forth. Each call to [method@Gtk.ProgressBar.pulse]
  * causes the block to move by a little bit (the amount of movement
- * per pulse is determined by gtk_progress_bar_set_pulse_step()).
+ * per pulse is determined by [method@Gtk.ProgressBar.set_pulse_step]).
  */
 void
 gtk_progress_bar_pulse (GtkProgressBar *pbar)
@@ -809,19 +836,20 @@ gtk_progress_bar_pulse (GtkProgressBar *pbar)
 
 /**
  * gtk_progress_bar_set_text:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  * @text: (allow-none): a UTF-8 string, or %NULL
  *
  * Causes the given @text to appear next to the progress bar.
  *
- * If @text is %NULL and #GtkProgressBar:show-text is %TRUE, the current
- * value of #GtkProgressBar:fraction will be displayed as a percentage.
+ * If @text is %NULL and [property@Gtk.ProgressBar:show-text] is %TRUE,
+ * the current value of [property@Gtk.ProgressBar:fraction] will be displayed
+ * as a percentage.
  *
- * If @text is non-%NULL and #GtkProgressBar:show-text is %TRUE, the text
- * will be displayed. In this case, it will not display the progress
+ * If @text is non-%NULL and [property@Gtk.ProgressBar:show-text] is %TRUE,
+ * the text will be displayed. In this case, it will not display the progress
  * percentage. If @text is the empty string, the progress bar will still
  * be styled and sized suitably for containing text, as long as
- * #GtkProgressBar:show-text is %TRUE.
+ * [property@Gtk.ProgressBar:show-text] is %TRUE.
  */
 void
 gtk_progress_bar_set_text (GtkProgressBar *pbar,
@@ -844,17 +872,18 @@ gtk_progress_bar_set_text (GtkProgressBar *pbar,
 
 /**
  * gtk_progress_bar_set_show_text:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  * @show_text: whether to show text
  *
  * Sets whether the progress bar will show text next to the bar.
- * The shown text is either the value of the #GtkProgressBar:text
- * property or, if that is %NULL, the #GtkProgressBar:fraction value,
+ *
+ * The shown text is either the value of the [property@Gtk.ProgressBar:text]
+ * property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction] value,
  * as a percentage.
  *
  * To make a progress bar that is styled and sized suitably for containing
- * text (even if the actual text is blank), set #GtkProgressBar:show-text to
- * %TRUE and #GtkProgressBar:text to the empty string (not %NULL).
+ * text (even if the actual text is blank), set [property@Gtk.ProgressBar:show-text]
+ * to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL).
  */
 void
 gtk_progress_bar_set_show_text (GtkProgressBar *pbar,
@@ -893,10 +922,11 @@ gtk_progress_bar_set_show_text (GtkProgressBar *pbar,
 
 /**
  * gtk_progress_bar_get_show_text:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
+ *
+ * Returns whether the `GtkProgressBar` shows text.
  *
- * Gets the value of the #GtkProgressBar:show-text property.
- * See gtk_progress_bar_set_show_text().
+ * See [method@Gtk.ProgressBar.set_show_text].
  *
  * Returns: %TRUE if text is shown in the progress bar
  */
@@ -910,11 +940,14 @@ gtk_progress_bar_get_show_text (GtkProgressBar *pbar)
 
 /**
  * gtk_progress_bar_set_pulse_step:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  * @fraction: fraction between 0.0 and 1.0
  *
  * Sets the fraction of total progress bar length to move the
- * bouncing block for each call to gtk_progress_bar_pulse().
+ * bouncing block.
+ *
+ * The bouncing block is moved when [method@Gtk.ProgressBar.pulse]
+ * is called.
  */
 void
 gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar,
@@ -975,9 +1008,11 @@ gtk_progress_bar_set_orientation (GtkProgressBar *pbar,
 
 /**
  * gtk_progress_bar_set_inverted:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  * @inverted: %TRUE to invert the progress bar
  *
+ * Sets whether the progress bar is inverted.
+ *
  * Progress bars normally grow from top to bottom or left to right.
  * Inverted progress bars grow in the opposite direction.
  */
@@ -999,12 +1034,12 @@ gtk_progress_bar_set_inverted (GtkProgressBar *pbar,
 
 /**
  * gtk_progress_bar_get_text:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
+ *
+ * Retrieves the text that is displayed with the progress bar.
  *
- * Retrieves the text that is displayed with the progress bar,
- * if any, otherwise %NULL. The return value is a reference
- * to the text, not a copy of it, so will become invalid
- * if you change the text in the progress bar.
+ * The return value is a reference to the text, not a copy of it,
+ * so will become invalid if you change the text in the progress bar.
  *
  * Returns: (nullable): text, or %NULL; this string is owned by the widget
  * and should not be modified or freed.
@@ -1019,7 +1054,7 @@ gtk_progress_bar_get_text (GtkProgressBar *pbar)
 
 /**
  * gtk_progress_bar_get_fraction:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  *
  * Returns the current fraction of the task that’s been completed.
  *
@@ -1035,9 +1070,11 @@ gtk_progress_bar_get_fraction (GtkProgressBar *pbar)
 
 /**
  * gtk_progress_bar_get_pulse_step:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  *
- * Retrieves the pulse step set with gtk_progress_bar_set_pulse_step().
+ * Retrieves the pulse step.
+ *
+ * See [method@Gtk.ProgressBar.set_pulse_step].
  *
  * Returns: a fraction from 0.0 to 1.0
  */
@@ -1051,9 +1088,9 @@ gtk_progress_bar_get_pulse_step (GtkProgressBar *pbar)
 
 /**
  * gtk_progress_bar_get_inverted:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  *
- * Gets the value set by gtk_progress_bar_set_inverted().
+ * Returns whether the progress bar is inverted.
  *
  * Returns: %TRUE if the progress bar is inverted
  */
@@ -1067,11 +1104,13 @@ gtk_progress_bar_get_inverted (GtkProgressBar *pbar)
 
 /**
  * gtk_progress_bar_set_ellipsize:
- * @pbar: a #GtkProgressBar
- * @mode: a #PangoEllipsizeMode
+ * @pbar: a `GtkProgressBar`
+ * @mode: a `PangoEllipsizeMode`
+ *
+ * Sets the mode used to ellipsize the text.
  *
- * Sets the mode used to ellipsize (add an ellipsis: "...") the
- * text if there is not enough space to render the entire string.
+ * The text is ellipsized if there is not enough space
+ * to render the entire string.
  */
 void
 gtk_progress_bar_set_ellipsize (GtkProgressBar     *pbar,
@@ -1094,12 +1133,13 @@ gtk_progress_bar_set_ellipsize (GtkProgressBar     *pbar,
 
 /**
  * gtk_progress_bar_get_ellipsize:
- * @pbar: a #GtkProgressBar
+ * @pbar: a `GtkProgressBar`
  *
  * Returns the ellipsizing position of the progress bar.
- * See gtk_progress_bar_set_ellipsize().
  *
- * Returns: #PangoEllipsizeMode
+ * See [method@Gtk.ProgressBar.set_ellipsize].
+ *
+ * Returns: `PangoEllipsizeMode`
  */
 PangoEllipsizeMode
 gtk_progress_bar_get_ellipsize (GtkProgressBar *pbar)