[gtk/ebassi/gidocgen: 58/200] docs: Port GtkAboutDialog to the new syntax

[Emmanuele Bassi <ebassi src gnome org>]

commit d6fd7df778778d188e22469febe99a15d3793744
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Feb 18 13:38:55 2021 +0000

    docs: Port GtkAboutDialog to the new syntax
    
    We should also clean up the annotations, while we're at it.

 gtk/gtkaboutdialog.c | 318 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 172 insertions(+), 146 deletions(-)
---
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 6e806856b2..da1ffc6c0e 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -65,32 +65,35 @@
  * @Short_description: Display information about an application
  * @Title: GtkAboutDialog
  *
- * The GtkAboutDialog offers a simple way to display information about
+ * The `GtkAboutDialog` offers a simple way to display information about
  * a program like its logo, name, copyright, website and license. It is
  * also possible to give credits to the authors, documenters, translators
  * and artists who have worked on the program. An about dialog is typically
  * opened when the user selects the `About` option from the `Help` menu.
  * All parts of the dialog are optional.
  *
- * About dialogs often contain links and email addresses. GtkAboutDialog
- * displays these as clickable links. By default, it calls gtk_show_uri()
+ * ![An example GtkAboutDialog](aboutdialog.png)
+ *
+ * About dialogs often contain links and email addresses. `GtkAboutDialog`
+ * displays these as clickable links. By default, it calls [func@Gtk.show_uri]
  * when a user clicks one. The behaviour can be overridden with the
- * #GtkAboutDialog::activate-link signal.
+ * [signal@Gtk.AboutDialog::activate-link] signal.
  *
  * To specify a person with an email address, use a string like
- * "Edgar Allan Poe <edgar\@poe.com>". To specify a website with a title,
- * use a string like "GTK team http://www.gtk.org";.
+ * `Edgar Allan Poe <edgar poe com>`. To specify a website with a title,
+ * use a string like `GTK team https://www.gtk.org`.
  *
- * To make constructing a GtkAboutDialog as convenient as possible, you can
- * use the function gtk_show_about_dialog() which constructs and shows a dialog
- * and keeps it around so that it can be shown again.
+ * To make constructing a `GtkAboutDialog` as convenient as possible, you can
+ * use the function [func@Gtk.show_about_dialog] which constructs and shows
+ * a dialog and keeps it around so that it can be shown again.
  *
  * Note that GTK sets a default title of `_("About %s")` on the dialog
- * window (where \%s is replaced by the name of the application, but in
+ * window (where `%s` is replaced by the name of the application, but in
  * order to ensure proper translation of the title, applications should
- * set the title property explicitly when constructing a GtkAboutDialog,
+ * set the title property explicitly when constructing a `GtkAboutDialog`,
  * as shown in the following example:
- * |[<!-- language="C" -->
+ *
+ * ```c
  * GFile *logo_file = g_file_new_for_path ("./logo.png");
  * GdkTexture *example_logo = gdk_texture_new_from_file (logo_file, NULL);
  * g_object_unref (logo_file);
@@ -100,12 +103,12 @@
  *                        "logo", example_logo,
  *                        "title", _("About ExampleCode"),
  *                        NULL);
- * ]|
+ * ```
  *
- * # CSS nodes
+ * ## CSS nodes
  *
- * GtkAboutDialog has a single CSS node with the name window and style
- * class .aboutdialog.
+ * `GtkAboutDialog` has a single CSS node with the name `window` and style
+ * class `.aboutdialog`.
 
  */
 
@@ -349,11 +352,12 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    * @label: The object on which the signal was emitted
    * @uri: the URI that is activated
    *
-   * The signal which gets emitted to activate a URI.
+   * A signal emitted every time a URL is activated.
+   *
    * Applications may connect to it to override the default behaviour,
-   * which is to call gtk_show_uri().
+   * which is to call [func@Gtk.show_uri].
    *
-   * Returns: %TRUE if the link has been activated
+   * Returns: `TRUE` if the link has been activated
    */
   signals[ACTIVATE_LINK] =
     g_signal_new (I_("activate-link"),
@@ -368,7 +372,8 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    * GtkAboutDialog:program-name:
    *
    * The name of the program.
-   * If this is not set, it defaults to g_get_application_name().
+   *
+   * If this is not set, it defaults to `g_get_application_name()`.
    */
   props[PROP_NAME] =
     g_param_spec_string ("program-name",
@@ -404,9 +409,11 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:comments:
    *
-   * Comments about the program. This string is displayed in a label
-   * in the main dialog, thus it should be a short explanation of
-   * the main purpose of the program, not a detailed list of features.
+   * Comments about the program.
+   *
+   * This string is displayed in a label in the main dialog, thus it
+   * should be a short explanation of the main purpose of the program,
+   * not a detailed list of features.
    */
   props[PROP_COMMENTS] =
     g_param_spec_string ("comments",
@@ -418,17 +425,19 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:license:
    *
-   * The license of the program. This string is displayed in a
-   * text view in a secondary dialog, therefore it is fine to use
-   * a long multi-paragraph text. Note that the text is only wrapped
-   * in the text view if the "wrap-license" property is set to %TRUE;
+   * The license of the program, as free form text.
+   *
+   * This string is displayed in a text view in a secondary dialog, therefore
+   * it is fine to use a long multi-paragraph text. Note that the text is only
+   * wrapped in the text view if the "wrap-license" property is set to `TRUE`;
    * otherwise the text itself must contain the intended linebreaks.
-   * When setting this property to a non-%NULL value, the
-   * #GtkAboutDialog:license-type property is set to %GTK_LICENSE_CUSTOM
-   * as a side effect.
    *
-   * The text may contain links in this format <http://www.some.place/>
-   * and email references in the form <mail-to some body>, and these will
+   * When setting this property to a non-`NULL` value, the
+   * [property@Gtk.AboutDialog:license-type] property is set to
+   * `GTK_LICENSE_CUSTOM` as a side effect.
+   *
+   * The text may contain links in this format `<http://www.some.place/>`
+   * and email references in the form `<mail-to some body>`, and these will
    * be converted into clickable links.
    */
   props[PROP_LICENSE] =
@@ -442,12 +451,13 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    * GtkAboutDialog:system-information:
    *
    * Information about the system on which the program is running.
-   * This is displayed in a separate tab, therefore it is fine to use
-   * a long multi-paragraph text. Note that the text should contain
+   *
+   * This information is displayed in a separate tab, therefore it is fine
+   * to use a long multi-paragraph text. Note that the text should contain
    * the intended linebreaks.
    *
-   * The text may contain links in this format <http://www.some.place/>
-   * and email references in the form <mail-to some body>, and these will
+   * The text may contain links in this format `<http://www.some.place/>`
+   * and email references in the form `<mail-to some body>`, and these will
    * be converted into clickable links.
    */
   props[PROP_SYSTEM_INFORMATION] =
@@ -460,20 +470,20 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:license-type:
    *
-   * The license of the program, as a value of the %GtkLicense enumeration.
+   * The license of the program, as a value of the [enum@Gtk.License] enumeration.
    *
-   * The #GtkAboutDialog will automatically fill out a standard disclaimer
+   * The `GtkAboutDialog` will automatically fill out a standard disclaimer
    * and link the user to the appropriate online resource for the license
    * text.
    *
-   * If %GTK_LICENSE_UNKNOWN is used, the link used will be the same
-   * specified in the #GtkAboutDialog:website property.
+   * If `GTK_LICENSE_UNKNOWN` is used, the link used will be the same
+   * specified in the [property@Gtk.AboutDialog:website] property.
    *
-   * If %GTK_LICENSE_CUSTOM is used, the current contents of the
-   * #GtkAboutDialog:license property are used.
+   * If `GTK_LICENSE_CUSTOM` is used, the current contents of the
+   * [property@Gtk.AboutDialog:license] property are used.
    *
-   * For any other #GtkLicense value, the contents of the
-   * #GtkAboutDialog:license property are also set by this property as
+   * For any other [enum@Gtk.License] value, the contents of the
+   * [property@Gtk.AboutDialog:license] property are also set by this property as
    * a side effect.
    */
   props[PROP_LICENSE_TYPE] =
@@ -488,7 +498,8 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    * GtkAboutDialog:website:
    *
    * The URL for the link to the website of the program.
-   * This should be a string starting with "http://.
+   *
+   * This should be a string starting with `http://` or `https://`.
    */
   props[PROP_WEBSITE] =
     g_param_spec_string ("website",
@@ -512,7 +523,8 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:authors:
    *
-   * The authors of the program, as a %NULL-terminated array of strings.
+   * The authors of the program, as a `NULL`-terminated array of strings.
+   *
    * Each string may contain email addresses and URLs, which will be displayed
    * as links, see the introduction for more details.
    */
@@ -526,7 +538,8 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:documenters:
    *
-   * The people documenting the program, as a %NULL-terminated array of strings.
+   * The people documenting the program, as a `NULL`-terminated array of strings.
+   *
    * Each string may contain email addresses and URLs, which will be displayed
    * as links, see the introduction for more details.
    */
@@ -540,9 +553,11 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:artists:
    *
-   * The people who contributed artwork to the program, as a %NULL-terminated
-   * array of strings. Each string may contain email addresses and URLs, which
-   * will be displayed as links, see the introduction for more details.
+   * The people who contributed artwork to the program, as a `NULL`-terminated
+   * array of strings.
+   *
+   * Each string may contain email addresses and URLs, which will be displayed
+   * as links.
    */
   props[PROP_ARTISTS] =
     g_param_spec_boxed ("artists",
@@ -555,6 +570,7 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    * GtkAboutDialog:translator-credits:
    *
    * Credits to the translators. This string should be marked as translatable.
+   *
    * The string may contain email addresses and URLs, which will be displayed
    * as links, see the introduction for more details.
    */
@@ -568,8 +584,10 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:logo:
    *
-   * A logo for the about box. If it is %NULL, the default window icon
-   * set with gtk_window_set_default_icon_name() will be used.
+   * A logo for the about box.
+   *
+   * If it is `NULL`, the default window icon set with
+   * [id@gtk_window_set_default_icon_name] will be used.
    */
   props[PROP_LOGO] =
     g_param_spec_object ("logo",
@@ -581,8 +599,9 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:logo-icon-name:
    *
-   * A named icon to use as the logo for the about box. This property
-   * overrides the #GtkAboutDialog:logo property.
+   * A named icon to use as the logo for the about box.
+   *
+   * This property overrides the [property@Gtk.AboutDialog:logo] property.
    */
   props[PROP_LOGO_ICON_NAME] =
     g_param_spec_string ("logo-icon-name",
@@ -960,7 +979,7 @@ update_website (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_get_program_name:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the program name displayed in the about dialog.
  *
@@ -1000,11 +1019,12 @@ update_name_version (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_program_name:
- * @about: a #GtkAboutDialog
- * @name: the program name
+ * @about: a `GtkAboutDialog`
+ * @name: (nullable): the program name
  *
  * Sets the name to display in the about dialog.
- * If this is not set, it defaults to g_get_application_name().
+ *
+ * If `name` is not set, it defaults to `g_get_application_name()`.
  */
 void
 gtk_about_dialog_set_program_name (GtkAboutDialog *about,
@@ -1026,7 +1046,7 @@ gtk_about_dialog_set_program_name (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_version:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the version string.
  *
@@ -1043,8 +1063,8 @@ gtk_about_dialog_get_version (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_version:
- * @about: a #GtkAboutDialog
- * @version: (allow-none): the version string
+ * @about: a `GtkAboutDialog`
+ * @version: (nullable): the version string
  *
  * Sets the version string to display in the about dialog.
  */
@@ -1067,7 +1087,7 @@ gtk_about_dialog_set_version (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_copyright:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the copyright string.
  *
@@ -1084,10 +1104,11 @@ gtk_about_dialog_get_copyright (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_copyright:
- * @about: a #GtkAboutDialog
- * @copyright: (allow-none): the copyright string
+ * @about: a `GtkAboutDialog`
+ * @copyright: (nullable): the copyright string
  *
  * Sets the copyright string to display in the about dialog.
+ *
  * This should be a short string of one or two lines.
  */
 void
@@ -1119,7 +1140,7 @@ gtk_about_dialog_set_copyright (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_comments:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the comments string.
  *
@@ -1136,10 +1157,11 @@ gtk_about_dialog_get_comments (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_comments:
- * @about: a #GtkAboutDialog
- * @comments: (allow-none): a comments string
+ * @about: a `GtkAboutDialog`
+ * @comments: (nullable): a comments string
  *
  * Sets the comments string to display in the about dialog.
+ *
  * This should be a short string of one or two lines.
  */
 void
@@ -1169,7 +1191,7 @@ gtk_about_dialog_set_comments (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_license:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the license information.
  *
@@ -1186,12 +1208,13 @@ gtk_about_dialog_get_license (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_license:
- * @about: a #GtkAboutDialog
- * @license: (allow-none): the license information or %NULL
+ * @about: a `GtkAboutDialog`
+ * @license: (nullable): the license information
  *
  * Sets the license information to be displayed in the secondary
- * license dialog. If @license is %NULL, the license button is
- * hidden.
+ * license dialog.
+ *
+ * If `license` is `NULL`, the license button is hidden.
  */
 void
 gtk_about_dialog_set_license (GtkAboutDialog *about,
@@ -1224,7 +1247,7 @@ gtk_about_dialog_set_license (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_system_information:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the system information that is shown in the about dialog.
  *
@@ -1240,14 +1263,16 @@ gtk_about_dialog_get_system_information (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_system_information:
- * @about: a #GtkAboutDialog
- * @system_information: (allow-none): system information or %NULL
+ * @about: a `GtkAboutDialog`
+ * @system_information: (nullable): system information
  *
  * Sets the system information to be displayed in the about
- * dialog. If @system_information is %NULL, the system information
+ * dialog.
+ *
+ * If `system_information` is `NULL`, the system information
  * tab is hidden.
  *
- * See #GtkAboutDialog:system-information.
+ * See [property@Gtk.AboutDialog:system-information].
  */
 void
 gtk_about_dialog_set_system_information (GtkAboutDialog *about,
@@ -1264,12 +1289,12 @@ gtk_about_dialog_set_system_information (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_wrap_license:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
- * Returns whether the license text in @about is
+ * Returns whether the license text in the about dialog is
  * automatically wrapped.
  *
- * Returns: %TRUE if the license text is wrapped
+ * Returns: `TRUE` if the license text is wrapped
  */
 gboolean
 gtk_about_dialog_get_wrap_license (GtkAboutDialog *about)
@@ -1281,10 +1306,10 @@ gtk_about_dialog_get_wrap_license (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_wrap_license:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  * @wrap_license: whether to wrap the license
  *
- * Sets whether the license text in @about is
+ * Sets whether the license text in the about dialog should be
  * automatically wrapped.
  */
 void
@@ -1305,12 +1330,11 @@ gtk_about_dialog_set_wrap_license (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_website:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the website URL.
  *
- * Returns: (nullable): The website URL. The string is owned by the about
- *  dialog and must not be modified.
+ * Returns: (nullable) (transfer none): The website URL
  */
 const char *
 gtk_about_dialog_get_website (GtkAboutDialog *about)
@@ -1322,8 +1346,8 @@ gtk_about_dialog_get_website (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_website:
- * @about: a #GtkAboutDialog
- * @website: (allow-none): a URL string starting with "http://";
+ * @about: a `GtkAboutDialog`
+ * @website: (nullable): a URL string starting with `http://`
  *
  * Sets the URL to use for the website link.
  */
@@ -1346,12 +1370,11 @@ gtk_about_dialog_set_website (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_website_label:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the label used for the website link.
  *
- * Returns: (nullable): The label used for the website link. The string is
- *     owned by the about dialog and must not be modified.
+ * Returns: (nullable) (transfer none): The label used for the website link.
  */
 const char *
 gtk_about_dialog_get_website_label (GtkAboutDialog *about)
@@ -1363,7 +1386,7 @@ gtk_about_dialog_get_website_label (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_website_label:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  * @website_label: the label used for the website link
  *
  * Sets the label to be used for the website link.
@@ -1387,13 +1410,13 @@ gtk_about_dialog_set_website_label (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_authors:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the string which are displayed in the authors tab
  * of the secondary credits dialog.
  *
  * Returns: (array zero-terminated=1) (transfer none): A
- *  %NULL-terminated string array containing the authors. The array is
+ *  `NULL`-terminated string array containing the authors. The array is
  *  owned by the about dialog and must not be modified.
  */
 const char * const *
@@ -1406,10 +1429,10 @@ gtk_about_dialog_get_authors (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_authors:
- * @about: a #GtkAboutDialog
- * @authors: (array zero-terminated=1): a %NULL-terminated array of strings
+ * @about: a `GtkAboutDialog`
+ * @authors: (array zero-terminated=1): the authors of the application
  *
- * Sets the strings which are displayed in the authors tab
+ * Sets the strings which are displayed in the "Authors" tab
  * of the secondary credits dialog.
  */
 void
@@ -1431,13 +1454,13 @@ gtk_about_dialog_set_authors (GtkAboutDialog  *about,
 
 /**
  * gtk_about_dialog_get_documenters:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
- * Returns the string which are displayed in the documenters
+ * Returns the string which are displayed in the "Documenters"
  * tab of the secondary credits dialog.
  *
  * Returns: (array zero-terminated=1) (transfer none): A
- *  %NULL-terminated string array containing the documenters. The
+ *  `NULL`-terminated string array containing the documenters. The
  *  array is owned by the about dialog and must not be modified.
  */
 const char * const *
@@ -1450,10 +1473,11 @@ gtk_about_dialog_get_documenters (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_documenters:
- * @about: a #GtkAboutDialog
- * @documenters: (array zero-terminated=1): a %NULL-terminated array of strings
+ * @about: a `GtkAboutDialog`
+ * @documenters: (array zero-terminated=1): the authors of the documentation
+ *   of the application
  *
- * Sets the strings which are displayed in the documenters tab
+ * Sets the strings which are displayed in the "Documenters" tab
  * of the credits dialog.
  */
 void
@@ -1475,13 +1499,13 @@ gtk_about_dialog_set_documenters (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_artists:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
- * Returns the string which are displayed in the artists tab
+ * Returns the string which are displayed in the "Artists" tab
  * of the secondary credits dialog.
  *
  * Returns: (array zero-terminated=1) (transfer none): A
- *  %NULL-terminated string array containing the artists. The array is
+ *  `NULL`-terminated string array containing the artists. The array is
  *  owned by the about dialog and must not be modified.
  */
 const char * const *
@@ -1494,10 +1518,11 @@ gtk_about_dialog_get_artists (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_artists:
- * @about: a #GtkAboutDialog
- * @artists: (array zero-terminated=1): a %NULL-terminated array of strings
+ * @about: a `GtkAboutDialog`
+ * @artists: (array zero-terminated=1): the authors of the artwork
+ *   of the application
  *
- * Sets the strings which are displayed in the artists tab
+ * Sets the strings which are displayed in the "Artists" tab
  * of the secondary credits dialog.
  */
 void
@@ -1519,13 +1544,12 @@ gtk_about_dialog_set_artists (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_translator_credits:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the translator credits string which is displayed
  * in the translators tab of the secondary credits dialog.
  *
- * Returns: (nullable): The translator credits string. The string is
- *   owned by the about dialog and must not be modified.
+ * Returns: (nullable): The translator credits string.
  */
 const char *
 gtk_about_dialog_get_translator_credits (GtkAboutDialog *about)
@@ -1537,24 +1561,26 @@ gtk_about_dialog_get_translator_credits (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_translator_credits:
- * @about: a #GtkAboutDialog
- * @translator_credits: (allow-none): the translator credits
+ * @about: a `GtkAboutDialog`
+ * @translator_credits: (nullable): the translator credits
  *
  * Sets the translator credits string which is displayed in
  * the translators tab of the secondary credits dialog.
  *
  * The intended use for this string is to display the translator
  * of the language which is currently used in the user interface.
- * Using gettext(), a simple way to achieve that is to mark the
+ * Using `gettext()`, a simple way to achieve that is to mark the
  * string for translation:
- * |[<!-- language="C" -->
+ *
+ * ```c
  * GtkWidget *about = gtk_about_dialog_new ();
  *  gtk_about_dialog_set_translator_credits (GTK_ABOUT_DIALOG (about),
  *                                           _("translator-credits"));
- * ]|
- * It is a good idea to use the customary msgid “translator-credits” for this
- * purpose, since translators will already know the purpose of that msgid, and
- * since #GtkAboutDialog will detect if “translator-credits” is untranslated
+ * ```
+ *
+ * It is a good idea to use the customary `msgid` “translator-credits” for this
+ * purpose, since translators will already know the purpose of that `msgid`, and
+ * since `GtkAboutDialog` will detect if “translator-credits” is untranslated
  * and hide the tab.
  */
 void
@@ -1576,15 +1602,14 @@ gtk_about_dialog_set_translator_credits (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_logo:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the paintable displayed as logo in the about dialog.
  *
  * Returns: (transfer none) (nullable): the paintable displayed as
- *   logo or %NULL if the logo is unset or has been set via
- *   gtk_about_dialog_set_logo_icon_name(). The
- *   paintable is owned by the about dialog. If you want to keep a
- *   reference to it, you have to call g_object_ref() on it.
+ *   logo or `NULL` if the logo is unset or has been set via
+ *   [method@Gtk.AboutDialog.set_logo_icon_name]. The
+ *   paintable is owned by the about dialog.
  */
 GdkPaintable *
 gtk_about_dialog_get_logo (GtkAboutDialog *about)
@@ -1599,8 +1624,8 @@ gtk_about_dialog_get_logo (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_logo:
- * @about: a #GtkAboutDialog
- * @logo: (allow-none): a #GdkPaintable, or %NULL
+ * @about: a `GtkAboutDialog`
+ * @logo: (nullable): a `GdkPaintable`
  *
  * Sets the logo in the about dialog.
  */
@@ -1625,14 +1650,13 @@ gtk_about_dialog_set_logo (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_logo_icon_name:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
  * Returns the icon name displayed as logo in the about dialog.
  *
- * Returns: (transfer none) (nullable): the icon name displayed as logo or %NULL
- *   if the logo has been set via gtk_about_dialog_set_logo().
- *   The string is owned by the dialog. If you want to keep a reference
- *   to it, you have to call g_strdup() on it.
+ * Returns: (transfer none) (nullable): the icon name displayed as logo,
+ *   or `NULL` if the logo has been set via [method@Gtk.AboutDialog.set_logo].
+ *   The string is owned by the dialog.
  */
 const char *
 gtk_about_dialog_get_logo_icon_name (GtkAboutDialog *about)
@@ -1647,8 +1671,8 @@ gtk_about_dialog_get_logo_icon_name (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_set_logo_icon_name:
- * @about: a #GtkAboutDialog
- * @icon_name: (allow-none): an icon name, or %NULL
+ * @about: a `GtkAboutDialog`
+ * @icon_name: (nullable): an icon name
  *
  * Sets the icon name to be displayed as logo in the about dialog.
  */
@@ -2146,9 +2170,9 @@ populate_system_page (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_new:
  *
- * Creates a new #GtkAboutDialog.
+ * Creates a new `GtkAboutDialog`.
  *
- * Returns: a newly created #GtkAboutDialog
+ * Returns: a newly created `GtkAboutDialog`
  */
 GtkWidget *
 gtk_about_dialog_new (void)
@@ -2169,11 +2193,13 @@ close_cb (GtkAboutDialog *about,
 
 /**
  * gtk_show_about_dialog:
- * @parent: (allow-none): transient parent, or %NULL for none
+ * @parent: (nullable): the parent top-level window
  * @first_property_name: the name of the first property
- * @...: value of first property, followed by more properties, %NULL-terminated
+ * @...: value of first property, followed by more pairs of property
+ *   name and value, `NULL`-terminated
+ *
+ * A convenience function for showing an application’s about dialog.
  *
- * This is a convenience function for showing an application’s about box.
  * The constructed dialog is associated with the parent window and
  * reused for future invocations of this function.
  */
@@ -2225,14 +2251,14 @@ gtk_show_about_dialog (GtkWindow   *parent,
 
 /**
  * gtk_about_dialog_set_license_type:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  * @license_type: the type of license
  *
- * Sets the license of the application showing the @about dialog from a
+ * Sets the license of the application showing the about dialog from a
  * list of known licenses.
  *
  * This function overrides the license set using
- * gtk_about_dialog_set_license().
+ * [method@Gtk.AboutDialog.set_license].
  */
 void
 gtk_about_dialog_set_license_type (GtkAboutDialog *about,
@@ -2295,11 +2321,11 @@ gtk_about_dialog_set_license_type (GtkAboutDialog *about,
 
 /**
  * gtk_about_dialog_get_license_type:
- * @about: a #GtkAboutDialog
+ * @about: a `GtkAboutDialog`
  *
- * Retrieves the license set using gtk_about_dialog_set_license_type()
+ * Retrieves the license set using [method@Gtk.AboutDialog.set_license_type].
  *
- * Returns: a #GtkLicense value
+ * Returns: a [enum@Gtk.License] value
  */
 GtkLicense
 gtk_about_dialog_get_license_type (GtkAboutDialog *about)
@@ -2311,11 +2337,11 @@ gtk_about_dialog_get_license_type (GtkAboutDialog *about)
 
 /**
  * gtk_about_dialog_add_credit_section:
- * @about: A #GtkAboutDialog
+ * @about: A `GtkAboutDialog`
  * @section_name: The name of the section
  * @people: (array zero-terminated=1): The people who belong to that section
  *
- * Creates a new section in the Credits page.
+ * Creates a new section in the "Credits" page.
  */
 void
 gtk_about_dialog_add_credit_section (GtkAboutDialog  *about,