[gtk/ebassi/gidocgen: 42/478] statusbar: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit b577fe534def5bbc2910e05ee967cc6d8819b047
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 19 16:02:40 2021 -0500

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

 gtk/gtkstatusbar.c | 80 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 41 insertions(+), 39 deletions(-)
---
diff --git a/gtk/gtkstatusbar.c b/gtk/gtkstatusbar.c
index df104af7d7..dd65995967 100644
--- a/gtk/gtkstatusbar.c
+++ b/gtk/gtkstatusbar.c
@@ -45,6 +45,8 @@
  * A `GtkStatusbar` widget is usually placed along the bottom of an application's
  * main [class@Gtk.Window].
  *
+ * ![An example GtkStatusbar](statusbar.png)
+ *
  * A `GtkStatusBar` may provide a regular commentary of the application's
  * status (as is usually the case in a web browser, for example), or may be
  * used to simply output a message when the status changes, (when an upload
@@ -53,26 +55,25 @@
  * Status bars in GTK maintain a stack of messages. The message at
  * the top of the each bar’s stack is the one that will currently be displayed.
  *
- * Any messages added to a statusbar’s stack must specify a
- * context id that is used to uniquely identify
- * the source of a message. This context id can be generated by
- * gtk_statusbar_get_context_id(), given a message and the statusbar that
- * it will be added to. Note that messages are stored in a stack, and when
- * choosing which message to display, the stack structure is adhered to,
- * regardless of the context identifier of a message.
+ * Any messages added to a statusbar’s stack must specify a context id that
+ * is used to uniquely identify the source of a message. This context id can
+ * be generated by [method@Gtk.Statusbar.get_context_id], given a message and
+ * the statusbar that it will be added to. Note that messages are stored in a
+ * stack, and when choosing which message to display, the stack structure is
+ * adhered to, regardless of the context identifier of a message.
  *
  * One could say that a statusbar maintains one stack of messages for
  * display purposes, but allows multiple message producers to maintain
  * sub-stacks of the messages they produced (via context ids).
  *
- * Status bars are created using gtk_statusbar_new().
+ * Status bars are created using [ctor Gtk Statusbar new].
  *
- * Messages are added to the bar’s stack with gtk_statusbar_push().
+ * Messages are added to the bar’s stack with [method Gtk Statusbar push].
  *
  * The message at the top of the stack can be removed using
- * gtk_statusbar_pop(). A message can be removed from anywhere in the
- * stack if its message id was recorded at the time it was added. This
- * is done using gtk_statusbar_remove().
+ * [method Gtk Statusbar pop]. A message can be removed from anywhere in the
+ * stack if its message id was recorded at the time it was added. This is done
+ * using [method@Gtk.Statusbar.remove].
  *
  * ## CSS node
  *
@@ -166,7 +167,7 @@ gtk_statusbar_class_init (GtkStatusbarClass *class)
    * @context_id: the context id of the relevant message/statusbar
    * @text: the message that was pushed
    *
-   * Is emitted whenever a new message gets pushed onto a statusbar's stack.
+   * Emitted whenever a new message gets pushed onto a statusbar's stack.
    */
   statusbar_signals[SIGNAL_TEXT_PUSHED] =
     g_signal_new (I_("text-pushed"),
@@ -185,7 +186,7 @@ gtk_statusbar_class_init (GtkStatusbarClass *class)
    * @context_id: the context id of the relevant message/statusbar
    * @text: the message that was just popped
    *
-   * Is emitted whenever a new message is popped off a statusbar's stack.
+   * Emitted whenever a new message is popped off a statusbar's stack.
    */
   statusbar_signals[SIGNAL_TEXT_POPPED] =
     g_signal_new (I_("text-popped"),
@@ -222,9 +223,9 @@ gtk_statusbar_init (GtkStatusbar *statusbar)
 /**
  * gtk_statusbar_new:
  *
- * Creates a new #GtkStatusbar ready for messages.
+ * Creates a new `GtkStatusbar` ready for messages.
  *
- * Returns: the new #GtkStatusbar
+ * Returns: the new `GtkStatusbar`
  */
 GtkWidget* 
 gtk_statusbar_new (void)
@@ -247,13 +248,14 @@ gtk_statusbar_update (GtkStatusbar *statusbar,
 
 /**
  * gtk_statusbar_get_context_id:
- * @statusbar: a #GtkStatusbar
- * @context_description: textual description of what context 
- *                       the new message is being used in
+ * @statusbar: a `GtkStatusbar`
+ * @context_description: textual description of what context
+ *   the new message is being used in
+ *
+ * Returns a new context identifier, given a description
+ * of the actual context.
  *
- * Returns a new context identifier, given a description 
- * of the actual context. Note that the description is 
- * not shown in the UI.
+ * Note that the description is not shown in the UI.
  *
  * Returns: an integer id
  */
@@ -307,15 +309,15 @@ gtk_statusbar_msg_free (GtkStatusbarMsg *msg)
 
 /**
  * gtk_statusbar_push:
- * @statusbar: a #GtkStatusbar
+ * @statusbar: a `GtkStatusbar`
  * @context_id: the message’s context id, as returned by
- *              gtk_statusbar_get_context_id()
+ *    gtk_statusbar_get_context_id()
  * @text: the message to add to the statusbar
- * 
+ *
  * Pushes a new message onto a statusbar’s stack.
  *
- * Returns: a message id that can be used with 
- *          gtk_statusbar_remove().
+ * Returns: a message id that can be used with
+ *   [method@Gtk.Statusbar.remove].
  */
 guint
 gtk_statusbar_push (GtkStatusbar *statusbar,
@@ -341,14 +343,14 @@ gtk_statusbar_push (GtkStatusbar *statusbar,
 
 /**
  * gtk_statusbar_pop:
- * @statusbar: a #GtkStatusbar
+ * @statusbar: a `GtkStatusbar`
  * @context_id: a context identifier
- * 
- * Removes the first message in the #GtkStatusbar’s stack
- * with the given context id. 
  *
- * Note that this may not change the displayed message, if 
- * the message at the top of the stack has a different 
+ * Removes the first message in the `GtkStatusbar`’s stack
+ * with the given context id.
+ *
+ * Note that this may not change the displayed message,
+ * if the message at the top of the stack has a different
  * context id.
  */
 void
@@ -388,11 +390,11 @@ gtk_statusbar_pop (GtkStatusbar *statusbar,
 
 /**
  * gtk_statusbar_remove:
- * @statusbar: a #GtkStatusbar
+ * @statusbar: a `GtkStatusbar`
  * @context_id: a context identifier
- * @message_id: a message identifier, as returned by gtk_statusbar_push()
+ * @message_id: a message identifier, as returned by [method Gtk Statusbar push]
  *
- * Forces the removal of a message from a statusbar’s stack. 
+ * Forces the removal of a message from a statusbar’s stack.
  * The exact @context_id and @message_id must be specified.
  */
 void
@@ -437,7 +439,7 @@ gtk_statusbar_remove (GtkStatusbar *statusbar,
 
 /**
  * gtk_statusbar_remove_all:
- * @statusbar: a #GtkStatusbar
+ * @statusbar: a `GtkStatusbar`
  * @context_id: a context identifier
  *
  * Forces the removal of all messages from a statusbar's
@@ -493,9 +495,9 @@ gtk_statusbar_remove_all (GtkStatusbar *statusbar,
 
 /**
  * gtk_statusbar_get_message:
- * @statusbar: a #GtkStatusbar
+ * @statusbar: a `GtkStatusbar`
  *
- * Retrieves the contents of the label in #GtkStatusbar.
+ * Retrieves the contents of the label in `GtkStatusbar`.
  *
  * Returns: (transfer none): the contents of the statusbar
  */