From 4fef62c38d55289482dd3c7475f2bd34d16cf9f7 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 18 Feb 2021 13:38:55 +0000 Subject: [PATCH] docs: Port GtkAboutDialog to the new syntax We should also clean up the annotations, while we're at it. --- gtk/gtkaboutdialog.c | 322 +++++++++++++++++++++++-------------------- 1 file changed, 174 insertions(+), 148 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 ". To specify a website with a title, - * use a string like "GTK team http://www.gtk.org". + * `Edgar Allan Poe `. 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: - * |[ + * + * ```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. - * Applications may connect to it to override the default behaviour, - * which is to call gtk_show_uri(). + * A signal emitted every time a URL is activated. * - * Returns: %TRUE if the link has been activated + * Applications may connect to it to override the default behaviour, + * which is to call [func@Gtk.show_uri]. + * + * 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; - * 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 license of the program, as free form text. * - * The text may contain links in this format - * and email references in the form , and these will + * 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 + * [property@Gtk.AboutDialog:license-type] property is set to + * `GTK_LICENSE_CUSTOM` as a side effect. + * + * The text may contain links in this format `` + * and email references in the form ``, 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 - * and email references in the form , and these will + * The text may contain links in this format `` + * and email references in the form ``, 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: - * |[ + * + * ```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,