From 23948a4db5e0be9e6174467e5185c745b560a2e7 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 4 Feb 2025 15:27:56 +0000 Subject: [PATCH] gkeyfile: Convert docs to gi-docgen linking syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Improve formatting while I’m there, and try and ensure all the docs in these two files matches the [guidelines](https://developer.gnome.org/documentation/guidelines/devel-docs.html#writing-api-references). Signed-off-by: Philip Withnall Helps: #3250 --- glib/gkeyfile.c | 712 +++++++++++++++++++++++++----------------------- 1 file changed, 376 insertions(+), 336 deletions(-) diff --git a/glib/gkeyfile.c b/glib/gkeyfile.c index bb0885a3d..3a994335f 100644 --- a/glib/gkeyfile.c +++ b/glib/gkeyfile.c @@ -79,8 +79,8 @@ * `GKeyFile` parses .ini-like config files. * * `GKeyFile` lets you parse, edit or create files containing groups of - * key-value pairs, which we call "key files" for lack of a better name. - * Several freedesktop.org specifications use key files now, e.g the + * key-value pairs, which we call ‘key files’ for lack of a better name. + * Several freedesktop.org specifications use key files. For example, the * [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/) * and the [Icon Theme Specification](https://specifications.freedesktop.org/icon-theme-spec/latest/). * @@ -110,31 +110,32 @@ * Booleans=true;false;true;true * ``` * - * Lines beginning with a '#' and blank lines are considered comments. + * Lines beginning with a `#` and blank lines are considered comments. * * Groups are started by a header line containing the group name enclosed - * in '[' and ']', and ended implicitly by the start of the next group or + * in `[` and `]`, and ended implicitly by the start of the next group or * the end of the file. Each key-value pair must be contained in a group. * * Key-value pairs generally have the form `key=value`, with the exception * of localized strings, which have the form `key[locale]=value`, with a * locale identifier of the form `lang_COUNTRY@MODIFIER` where `COUNTRY` - * and `MODIFIER` are optional. As a special case, the locale `C` is associated with - * the untranslated pair `key=value` (since GLib 2.84). Space before and after the '=' character - * are ignored. Newline, tab, carriage return and backslash characters in - * value are escaped as `\n`, `\t`, `\r`, and `\\\\`, respectively. To preserve - * leading spaces in values, these can also be escaped as `\s`. + * and `MODIFIER` are optional. As a special case, the locale `C` is associated + * with the untranslated pair `key=value` (since GLib 2.84). Space before and + * after the `=` character is ignored. Newline, tab, carriage return and + * backslash characters in value are escaped as `\n`, `\t`, `\r`, and `\\\\`, + * respectively. To preserve leading spaces in values, these can also be escaped + * as `\s`. * * Key files can store strings (possibly with localized variants), integers, * booleans and lists of these. Lists are separated by a separator character, - * typically ';' or ','. To use the list separator character in a value in + * typically `;` or `,`. To use the list separator character in a value in * a list, it has to be escaped by prefixing it with a backslash. * * This syntax is obviously inspired by the .ini files commonly met * on Windows, but there are some important differences: * - * - .ini files use the ';' character to begin comments, - * key files use the '#' character. + * - .ini files use the `;` character to begin comments, + * key files use the `#` character. * * - Key files do not allow for ungrouped keys meaning only * comments can precede the first group. @@ -142,11 +143,11 @@ * - Key files are always encoded in UTF-8. * * - Key and Group names are case-sensitive. For example, a group called - * [GROUP] is a different from [group]. + * `[GROUP]` is a different from `[group]`. * - * - .ini files don't have a strongly typed boolean entry type, - * they only have GetProfileInt(). In key files, only - * true and false (in lower case) are allowed. + * - .ini files don’t have a strongly typed boolean entry type, + * they only have `GetProfileInt()`. In key files, only + * `true` and `false` (in lower case) are allowed. * * Note that in contrast to the * [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/), @@ -213,10 +214,11 @@ /** * G_KEY_FILE_ERROR: * - * Error domain for key file parsing. Errors in this domain will - * be from the #GKeyFileError enumeration. + * Error domain for key file parsing. * - * See #GError for information on error domains. + * Errors in this domain will be from the [enum@GLib.KeyFileError] enumeration. + * + * See [struct@GLib.Error] for information on error domains. */ /** @@ -252,6 +254,7 @@ * * The name of the main group of a desktop entry file, as defined in the * [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/). + * * Consult the specification for more * details about the meanings of the keys below. * @@ -261,12 +264,12 @@ /** * G_KEY_FILE_DESKTOP_KEY_TYPE: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string * giving the type of the desktop entry. * - * Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION, - * %G_KEY_FILE_DESKTOP_TYPE_LINK, or - * %G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. + * Usually [const@GLib.KEY_FILE_DESKTOP_TYPE_APPLICATION], + * [const@GLib.KEY_FILE_DESKTOP_TYPE_LINK], or + * [const@GLib.KEY_FILE_DESKTOP_TYPE_DIRECTORY]. * * Since: 2.14 */ @@ -274,7 +277,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_VERSION: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string * giving the version of the Desktop Entry Specification used for * the desktop entry file. * @@ -284,7 +287,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_NAME: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized * string giving the specific name of the desktop entry. * * Since: 2.14 @@ -293,7 +296,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized * string giving the generic name of the desktop entry. * * Since: 2.14 @@ -302,7 +305,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean * stating whether the desktop entry should be shown in menus. * * Since: 2.14 @@ -311,7 +314,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_COMMENT: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized * string giving the tooltip for the desktop entry. * * Since: 2.14 @@ -320,7 +323,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_ICON: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized * string giving the name of the icon to be displayed for the desktop * entry. * @@ -330,7 +333,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_HIDDEN: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean * stating whether the desktop entry has been deleted by the user. * * Since: 2.14 @@ -339,7 +342,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of * strings identifying the environments that should display the * desktop entry. * @@ -349,7 +352,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of * strings identifying the environments that should not display the * desktop entry. * @@ -359,10 +362,11 @@ /** * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string * giving the file name of a binary on disk used to determine if the - * program is actually installed. It is only valid for desktop entries - * with the `Application` type. + * program is actually installed. + * + * It is only valid for desktop entries with the `Application` type. * * Since: 2.14 */ @@ -370,9 +374,10 @@ /** * G_KEY_FILE_DESKTOP_KEY_EXEC: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * giving the command line to execute. It is only valid for desktop - * entries with the `Application` type. + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string + * giving the command line to execute. + * + * It is only valid for desktop entries with the `Application` type. * * Since: 2.14 */ @@ -380,9 +385,10 @@ /** * G_KEY_FILE_DESKTOP_KEY_PATH: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * containing the working directory to run the program in. It is only - * valid for desktop entries with the `Application` type. + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string + * containing the working directory to run the program in. + * + * It is only valid for desktop entries with the `Application` type. * * Since: 2.14 */ @@ -390,7 +396,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_TERMINAL: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean * stating whether the program should be run in a terminal window. * * It is only valid for desktop entries with the `Application` type. @@ -401,7 +407,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list * of strings giving the MIME types supported by this desktop entry. * * Since: 2.14 @@ -410,7 +416,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_CATEGORIES: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list * of strings giving the categories in which the desktop entry * should be shown in a menu. * @@ -420,7 +426,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean * stating whether the application supports the * [Startup Notification Protocol Specification](https://specifications.freedesktop.org/startup-notification-spec/latest/). * @@ -430,10 +436,11 @@ /** * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is string * identifying the WM class or name hint of a window that the application - * will create, which can be used to emulate Startup Notification with - * older applications. + * will create, which can be used to emulate + * [Startup Notification](https://specifications.freedesktop.org/startup-notification-spec/latest/) + * with older applications. * * Since: 2.14 */ @@ -441,9 +448,10 @@ /** * G_KEY_FILE_DESKTOP_KEY_URL: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * giving the URL to access. It is only valid for desktop entries - * with the `Link` type. + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string + * giving the URL to access. + * + * It is only valid for desktop entries with the `Link` type. * * Since: 2.14 */ @@ -451,7 +459,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean * set to true if the application is D-Bus activatable. * * Since: 2.38 @@ -460,7 +468,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_ACTIONS: * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list + * A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string list * giving the available application actions. * * Since: 2.38 @@ -469,7 +477,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_APPLICATION: * - * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop * entries representing applications. * * Since: 2.14 @@ -478,7 +486,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_LINK: * - * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop * entries representing links to documents. * * Since: 2.14 @@ -487,7 +495,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY: * - * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop * entries representing directories. * * Since: 2.14 @@ -678,12 +686,14 @@ g_key_file_clear (GKeyFile *key_file) /** * g_key_file_new: * - * Creates a new empty #GKeyFile object. Use - * g_key_file_load_from_file(), g_key_file_load_from_data(), - * g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to + * Creates a new empty [struct@GLib.KeyFile] object. + * + * Use [method@GLib.KeyFile.load_from_file], + * [method@GLib.KeyFile.load_from_data], [method@GLib.KeyFile.load_from_dirs] or + * [method@GLib.KeyFile.load_from_data_dirs] to * read an existing key file. * - * Returns: (transfer full): an empty #GKeyFile. + * Returns: (transfer full): an empty [struct@GLib.KeyFile]. * * Since: 2.6 **/ @@ -701,12 +711,13 @@ g_key_file_new (void) /** * g_key_file_set_list_separator: - * @key_file: a #GKeyFile + * @key_file: a key file * @separator: the separator * - * Sets the character which is used to separate - * values in lists. Typically ';' or ',' are used - * as separators. The default list separator is ';'. + * Sets the character which is used to separate values in lists. + * + * Typically `;` or `,` are used as separators. The default list separator + * is `;`. * * Since: 2.6 */ @@ -882,21 +893,21 @@ g_key_file_load_from_fd (GKeyFile *key_file, /** * g_key_file_load_from_file: - * @key_file: an empty #GKeyFile struct + * @key_file: an empty key file * @file: (type filename): the path of a filename to load, in the GLib filename encoding - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL + * @flags: flags from [flags@GLib.KeyFileFlags] + * @error: return location for a [struct@GLib.Error] * - * Loads a key file into an empty #GKeyFile structure. + * Loads a key file into an empty [struct@GLib.KeyFile] structure. * * If the OS returns an error when opening or reading the file, a - * %G_FILE_ERROR is returned. If there is a problem parsing the file, a - * %G_KEY_FILE_ERROR is returned. + * [error@GLib.FileError] is returned. If there is a problem parsing the file, + * a [error@GLib.KeyFileError] is returned. * - * This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the - * @file is not found, %G_FILE_ERROR_NOENT is returned. + * This function will never return a [error@GLib.KeyFileError.NOT_FOUND] + * error. If the @file is not found, [error@GLib.FileError.NOENT] is returned. * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise + * Returns: true if a key file could be loaded, false otherwise * * Since: 2.6 **/ @@ -938,16 +949,17 @@ g_key_file_load_from_file (GKeyFile *key_file, /** * g_key_file_load_from_data: - * @key_file: an empty #GKeyFile struct + * @key_file: an empty key file * @data: key file loaded in memory - * @length: the length of @data in bytes (or (gsize)-1 if data is nul-terminated) - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL + * @length: the length of @data in bytes (or `(gsize)-1` if data is nul-terminated) + * @flags: flags from [flags@GLib.KeyFileFlags] + * @error: return location for a [struct@GLib.Error] * - * Loads a key file from memory into an empty #GKeyFile structure. - * If the object cannot be created then %error is set to a #GKeyFileError. + * Loads a key file from memory into an empty [struct@GLib.KeyFile] structure. * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise + * If the object cannot be created then a [error@GLib.KeyFileError is returned. + * + * Returns: true if a key file could be loaded, false otherwise * * Since: 2.6 **/ @@ -994,15 +1006,17 @@ g_key_file_load_from_data (GKeyFile *key_file, /** * g_key_file_load_from_bytes: - * @key_file: an empty #GKeyFile struct - * @bytes: a #GBytes - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL + * @key_file: an empty [struct@GLib.KeyFile] struct + * @bytes: a [struct@GLib.Bytes] + * @flags: flags from [flags@GLib.KeyFileFlags] + * @error: return location for a [struct@GLib.Error] * - * Loads a key file from the data in @bytes into an empty #GKeyFile structure. - * If the object cannot be created then %error is set to a #GKeyFileError. + * Loads a key file from the data in @bytes into an empty [struct@GLib.KeyFile] + * structure. * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise + * If the object cannot be created then a [error@GLib.KeyFileError] is returned. + * + * Returns: true if a key file could be loaded, false otherwise * * Since: 2.50 **/ @@ -1024,25 +1038,25 @@ g_key_file_load_from_bytes (GKeyFile *key_file, /** * g_key_file_load_from_dirs: - * @key_file: an empty #GKeyFile struct + * @key_file: an empty [struct@GLib.KeyFile] struct * @file: (type filename): a relative path to a filename to open and parse - * @search_dirs: (array zero-terminated=1) (element-type filename): %NULL-terminated array of directories to search - * @full_path: (out) (type filename) (optional): return location for a string containing the full path - * of the file, or %NULL - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL + * @search_dirs: (array zero-terminated=1) (element-type filename): `NULL`-terminated + * array of directories to search + * @full_path: (out) (type filename) (optional): return location for a string + * containing the full path of the file, or `NULL` to ignore + * @flags: flags from [flags@GLib.KeyFileFlags] + * @error: return location for a [struct@GLib.Error] * - * This function looks for a key file named @file in the paths - * specified in @search_dirs, loads the file into @key_file and - * returns the file's full path in @full_path. + * Looks for a key file named @file in the paths specified in @search_dirs, + * loads the file into @key_file and returns the file’s full path in @full_path. * * If the file could not be found in any of the @search_dirs, - * %G_KEY_FILE_ERROR_NOT_FOUND is returned. If + * [error@GLib.KeyFileError.NOT_FOUND] is returned. If * the file is found but the OS returns an error when opening or reading the - * file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a - * %G_KEY_FILE_ERROR is returned. + * file, a [error@GLib.FileError] is returned. If there is a problem parsing the + * file, a [error@GLib.KeyFileError] is returned. * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise + * Returns: true if a key file could be loaded, false otherwise * * Since: 2.14 **/ @@ -1103,20 +1117,22 @@ g_key_file_load_from_dirs (GKeyFile *key_file, /** * g_key_file_load_from_data_dirs: - * @key_file: an empty #GKeyFile struct + * @key_file: an empty [struct@GLib.KeyFile] struct * @file: (type filename): a relative path to a filename to open and parse - * @full_path: (out) (type filename) (optional): return location for a string containing the full path - * of the file, or %NULL - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL + * @full_path: (out) (type filename) (optional): return location for a string + * containing the full path of the file, or `NULL` to ignore + * @flags: flags from [flags@GLib.KeyFileFlags] + * @error: return location for a [struct@GLib.Error] * - * This function looks for a key file named @file in the paths - * returned from g_get_user_data_dir() and g_get_system_data_dirs(), - * loads the file into @key_file and returns the file's full path in - * @full_path. If the file could not be loaded then an %error is - * set to either a #GFileError or #GKeyFileError. + * Looks for a key file named @file in the paths returned from + * [func@GLib.get_user_data_dir] and [func@GLib.get_system_data_dirs], + * loads the file into @key_file and returns the file’s full path in + * @full_path. * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise + * If the file could not be loaded then either a [error@GLib.FileError] or + * [error@GLib.KeyFileError] is returned. + * + * Returns: true if a key file could be loaded, false otherwise * Since: 2.6 **/ gboolean @@ -1161,7 +1177,7 @@ g_key_file_load_from_data_dirs (GKeyFile *key_file, /** * g_key_file_ref: (skip) - * @key_file: a #GKeyFile + * @key_file: a key file * * Increases the reference count of @key_file. * @@ -1181,11 +1197,13 @@ g_key_file_ref (GKeyFile *key_file) /** * g_key_file_free: (skip) - * @key_file: (transfer full): a #GKeyFile + * @key_file: (transfer full): a key file * * Clears all keys and groups from @key_file, and decreases the - * reference count by 1. If the reference count reaches zero, - * frees the key file and all its allocated memory. + * reference count by 1. + * + * If the reference count reaches zero, frees the key file and all its allocated + * memory. * * Since: 2.6 **/ @@ -1204,10 +1222,12 @@ g_key_file_free (GKeyFile *key_file) /** * g_key_file_unref: - * @key_file: (transfer full): a #GKeyFile + * @key_file: (transfer full): a key file * - * Decreases the reference count of @key_file by 1. If the reference count - * reaches zero, frees the key file and all its allocated memory. + * Decreases the reference count of @key_file by 1. + * + * If the reference count reaches zero, frees the key file and all its allocated + * memory. * * Since: 2.32 **/ @@ -1568,18 +1588,16 @@ g_key_file_flush_parse_buffer (GKeyFile *key_file, /** * g_key_file_to_data: - * @key_file: a #GKeyFile + * @key_file: a key file * @length: (out) (optional): return location for the length of the - * returned string, or %NULL - * @error: return location for a #GError, or %NULL + * returned string, or `NULL` to ignore + * @error: return location for a [struct@GLib.Error] * - * This function outputs @key_file as a string. + * Outputs @key_file as a string. * - * Note that this function never reports an error, - * so it is safe to pass %NULL as @error. + * Note that this function never reports an error. * - * Returns: a newly allocated string holding - * the contents of the #GKeyFile + * Returns: a newly allocated string holding the contents of the key file * * Since: 2.6 **/ @@ -1629,19 +1647,20 @@ g_key_file_to_data (GKeyFile *key_file, /** * g_key_file_get_keys: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name - * @length: (out) (optional): return location for the number of keys returned, or %NULL - * @error: return location for a #GError, or %NULL + * @length: (out) (optional): return location for the number of keys returned, + * or `NULL` to ignore + * @error: return location for a [struct@GLib.Error] * - * Returns all keys for the group name @group_name. The array of - * returned keys will be %NULL-terminated, so @length may - * optionally be %NULL. In the event that the @group_name cannot - * be found, %NULL is returned and @error is set to - * %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + * Returns all keys for the group name @group_name. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. - * Use g_strfreev() to free it. + * The array of returned keys will be `NULL`-terminated, so @length may + * optionally be `NULL`. If the @group_name cannot be found, + * [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. + * + * Returns: (array zero-terminated=1) (transfer full): a newly-allocated + * `NULL`-terminated array of strings. Use [func@GLib.strfreev] to free it. * * Since: 2.6 **/ @@ -1707,7 +1726,7 @@ g_key_file_get_keys (GKeyFile *key_file, /** * g_key_file_get_start_group: - * @key_file: a #GKeyFile + * @key_file: a key file * * Returns the name of the start group of the file. * @@ -1728,15 +1747,17 @@ g_key_file_get_start_group (GKeyFile *key_file) /** * g_key_file_get_groups: - * @key_file: a #GKeyFile - * @length: (out) (optional): return location for the number of returned groups, or %NULL + * @key_file: a key file + * @length: (out) (optional): return location for the number of returned groups, + * or `NULL` to ignore * * Returns all groups in the key file loaded with @key_file. - * The array of returned groups will be %NULL-terminated, so - * @length may optionally be %NULL. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. - * Use g_strfreev() to free it. + * The array of returned groups will be `NULL`-terminated, so + * @length may optionally be `NULL`. + * + * Returns: (array zero-terminated=1) (transfer full): a newly-allocated + * `NULL`-terminated array of strings. Use [func@GLib.strfreev] to free it. * Since: 2.6 **/ gchar ** @@ -1799,21 +1820,20 @@ set_not_found_key_error (const char *group_name, /** * g_key_file_get_value: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @error: return location for a #GError, or %NULL + * @error: return location for a [struct@GLib.Error] * * Returns the raw value associated with @key under @group_name. - * Use g_key_file_get_string() to retrieve an unescaped UTF-8 string. * - * In the event the key cannot be found, %NULL is returned and - * @error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the - * event that the @group_name cannot be found, %NULL is returned - * and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + * Use [method@GLib.KeyFile.get_string] to retrieve an unescaped UTF-8 string. * + * If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] + * is returned. If the @group_name cannot be found, + * [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. * - * Returns: a newly allocated string or %NULL if the specified + * Returns: a newly allocated string or `NULL` if the specified * key cannot be found. * * Since: 2.6 @@ -1855,7 +1875,7 @@ g_key_file_get_value (GKeyFile *key_file, /** * g_key_file_set_value: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @value: a string @@ -1865,7 +1885,7 @@ g_key_file_get_value (GKeyFile *key_file, * If @key cannot be found then it is created. If @group_name cannot * be found then it is created. To set an UTF-8 string which may contain * characters that need escaping (such as newlines or spaces), use - * g_key_file_set_string(). + * [method@GLib.KeyFile.set_string]. * * Since: 2.6 **/ @@ -1908,21 +1928,21 @@ g_key_file_set_value (GKeyFile *key_file, /** * g_key_file_get_string: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @error: return location for a #GError, or %NULL + * @error: return location for a [struct@GLib.Error] * * Returns the string value associated with @key under @group_name. - * Unlike g_key_file_get_value(), this function handles escape sequences - * like \s. * - * In the event the key cannot be found, %NULL is returned and - * @error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the - * event that the @group_name cannot be found, %NULL is returned - * and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + * Unlike [method@GLib.KeyFile.get_value], this function handles escape + * sequences like `\s`. * - * Returns: a newly allocated string or %NULL if the specified + * If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. If the @group_name cannot be found, + * [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. + * + * Returns: a newly allocated string or `NULL` if the specified * key cannot be found. * * Since: 2.6 @@ -1989,15 +2009,16 @@ g_key_file_get_string (GKeyFile *key_file, /** * g_key_file_set_string: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @string: a string * * Associates a new string value with @key under @group_name. + * * If @key cannot be found then it is created. * If @group_name cannot be found then it is created. - * Unlike g_key_file_set_value(), this function handles characters + * Unlike [method@GLib.KeyFile.set_value], this function handles characters * that need escaping, such as newlines. * * Since: 2.6 @@ -2020,22 +2041,22 @@ g_key_file_set_string (GKeyFile *key_file, /** * g_key_file_get_string_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @length: (out) (optional): return location for the number of returned strings, or %NULL - * @error: return location for a #GError, or %NULL + * @length: (out) (optional): return location for the number of returned + * strings, or `NULL` to ignore + * @error: return location for a [struct@GLib.Error] * * Returns the values associated with @key under @group_name. * - * In the event the key cannot be found, %NULL is returned and - * @error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the - * event that the @group_name cannot be found, %NULL is returned - * and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + * If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. If the @group_name cannot be found, + * [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. * * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): - * a %NULL-terminated string array or %NULL if the specified - * key cannot be found. The array should be freed with g_strfreev(). + * a `NULL`-terminated string array or `NULL` if the specified + * key cannot be found. The array should be freed with [func@GLib.strfreev]. * * Since: 2.6 **/ @@ -2119,13 +2140,15 @@ g_key_file_get_string_list (GKeyFile *key_file, /** * g_key_file_set_string_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values + * @list: (array zero-terminated=1 length=length) (element-type utf8): an array + * of string values * @length: number of string values in @list * * Associates a list of string values for @key under @group_name. + * * If @key cannot be found then it is created. * If @group_name cannot be found then it is created. * @@ -2162,13 +2185,14 @@ g_key_file_set_string_list (GKeyFile *key_file, /** * g_key_file_set_locale_string: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @locale: a locale identifier * @string: a string * * Associates a string value for @key and @locale under @group_name. + * * If the translation for @key cannot be found then it is created. * * If @locale is `C` then the untranslated value is set (since GLib 2.84). @@ -2198,28 +2222,30 @@ g_key_file_set_locale_string (GKeyFile *key_file, /** * g_key_file_get_locale_string: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @locale: (nullable): a locale identifier or %NULL - * @error: return location for a #GError, or %NULL + * @locale: (nullable): a locale identifier or `NULL` to use the current locale + * @error: return location for a [struct@GLib.Error] * * Returns the value associated with @key under @group_name - * translated in the given @locale if available. If @locale is - * %NULL then the current locale is assumed. + * translated in the given @locale if available. * * If @locale is `C` then the untranslated value is returned (since GLib 2.84). * - * If @locale is to be non-%NULL, or if the current locale will change over - * the lifetime of the #GKeyFile, it must be loaded with - * %G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. + * If @locale is `NULL` then the current locale is assumed. * - * If @key cannot be found then %NULL is returned and @error is set - * to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated + * If @locale is to be non-`NULL`, or if the current locale will change over + * the lifetime of the [struct@GLib.KeyFile], it must be loaded with + * [flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all + * locales. + * + * If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. If the value associated * with @key cannot be interpreted or no suitable translation can * be found then the untranslated value is returned. * - * Returns: a newly allocated string or %NULL if the specified + * Returns: a newly allocated string or `NULL` if the specified * key cannot be found. * * Since: 2.6 @@ -2291,22 +2317,22 @@ g_key_file_get_locale_string (GKeyFile *key_file, /** * g_key_file_get_locale_for_key: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @locale: (nullable): a locale identifier or %NULL + * @locale: (nullable): a locale identifier or `NULL` to use the current locale * * Returns the actual locale which the result of - * g_key_file_get_locale_string() or g_key_file_get_locale_string_list() - * came from. + * [method@GLib.KeyFile.get_locale_string] or + * [method@GLib.KeyFile.get_locale_string_list] came from. * - * If calling g_key_file_get_locale_string() or - * g_key_file_get_locale_string_list() with exactly the same @key_file, + * If calling [method@GLib.KeyFile.get_locale_string] or + * [method@GLib.KeyFile.get_locale_string_list] with exactly the same @key_file, * @group_name, @key and @locale, the result of those functions will * have originally been tagged with the locale that is the result of * this function. * - * Returns: (nullable): the locale from the file, or %NULL if the key was not + * Returns: (nullable): the locale from the file, or `NULL` if the key was not * found or the entry in the file was was untranslated * * Since: 2.56 @@ -2359,33 +2385,36 @@ g_key_file_get_locale_for_key (GKeyFile *key_file, /** * g_key_file_get_locale_string_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @locale: (nullable): a locale identifier or %NULL - * @length: (out) (optional): return location for the number of returned strings or %NULL - * @error: return location for a #GError or %NULL + * @locale: (nullable): a locale identifier or `NULL` to use the current locale + * @length: (out) (optional): return location for the number of returned strings + * or `NULL` to ignore + * @error: return location for a [struct@GLib.Error] * * Returns the values associated with @key under @group_name - * translated in the given @locale if available. If @locale is - * %NULL then the current locale is assumed. + * translated in the given @locale if available. * * If @locale is `C` then the untranslated value is returned (since GLib 2.84). * - * If @locale is to be non-%NULL, or if the current locale will change over - * the lifetime of the #GKeyFile, it must be loaded with - * %G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. + * If @locale is `NULL` then the current locale is assumed. * - * If @key cannot be found then %NULL is returned and @error is set - * to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated + * If @locale is to be non-`NULL`, or if the current locale will change over + * the lifetime of the [struct@GLib.KeyFile], it must be loaded with + * [flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all + * locales. + * + * If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. If the values associated * with @key cannot be interpreted or no suitable translations * can be found then the untranslated values are returned. The - * returned array is %NULL-terminated, so @length may optionally - * be %NULL. + * returned array is `NULL`-terminated, so @length may optionally + * be `NULL`. * - * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array - * or %NULL if the key isn't found. The string array should be freed - * with g_strfreev(). + * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): + * a newly allocated `NULL`-terminated string array or `NULL` if the key + * isn’t found. The string array should be freed with [func@GLib.strfreev]. * * Since: 2.6 **/ @@ -2440,19 +2469,21 @@ g_key_file_get_locale_string_list (GKeyFile *key_file, /** * g_key_file_set_locale_string_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @locale: a locale identifier - * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values + * @list: (array zero-terminated=1 length=length): a `NULL`-terminated array of + * locale string values * @length: the length of @list * * Associates a list of string values for @key and @locale under - * @group_name. If the translation for @key cannot be found then - * it is created. + * @group_name. * * If @locale is `C` then the untranslated value is set (since GLib 2.84). * + * If the translation for @key cannot be found then it is created. + * * Since: 2.6 **/ void @@ -2492,21 +2523,20 @@ g_key_file_set_locale_string_list (GKeyFile *key_file, /** * g_key_file_get_boolean: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @error: return location for a #GError + * @error: return location for a [struct@GLib.Error] * * Returns the value associated with @key under @group_name as a * boolean. * - * If @key cannot be found then %FALSE is returned and @error is set - * to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value - * associated with @key cannot be interpreted as a boolean then %FALSE - * is returned and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. + * If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. Likewise, if the value associated with @key cannot be interpreted + * as a boolean then [error@GLib.KeyFileError.INVALID_VALUE] is returned. * * Returns: the value associated with the key as a boolean, - * or %FALSE if the key was not found or could not be parsed. + * or false if the key was not found or could not be parsed. * * Since: 2.6 **/ @@ -2558,12 +2588,13 @@ g_key_file_get_boolean (GKeyFile *key_file, /** * g_key_file_set_boolean: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @value: %TRUE or %FALSE + * @value: true or false * * Associates a new boolean value with @key under @group_name. + * * If @key cannot be found then it is created. * * Since: 2.6 @@ -2584,24 +2615,23 @@ g_key_file_set_boolean (GKeyFile *key_file, /** * g_key_file_get_boolean_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @length: (out): the number of booleans returned - * @error: return location for a #GError + * @error: return location for a [struct@GLib.Error] * * Returns the values associated with @key under @group_name as * booleans. * - * If @key cannot be found then %NULL is returned and @error is set to - * %G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated - * with @key cannot be interpreted as booleans then %NULL is returned - * and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. + * If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. Likewise, if the values associated with @key cannot be interpreted + * as booleans then [error@GLib.KeyFileError.INVALID_VALUE] is returned. * * Returns: (array length=length) (element-type gboolean) (transfer container): - * the values associated with the key as a list of booleans, or %NULL if the + * the values associated with the key as a list of booleans, or `NULL` if the * key was not found or could not be parsed. The returned list of booleans - * should be freed with g_free() when no longer needed. + * should be freed with [func@GLib.free] when no longer needed. * * Since: 2.6 **/ @@ -2662,15 +2692,15 @@ g_key_file_get_boolean_list (GKeyFile *key_file, /** * g_key_file_set_boolean_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @list: (array length=length): an array of boolean values * @length: length of @list * - * Associates a list of boolean values with @key under @group_name. + * Associates a list of boolean values with @key under @group_name. + * * If @key cannot be found then it is created. - * If @group_name is %NULL, the start_group is used. * * Since: 2.6 **/ @@ -2704,22 +2734,21 @@ g_key_file_set_boolean_list (GKeyFile *key_file, /** * g_key_file_get_integer: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @error: return location for a #GError + * @error: return location for a [struct@GLib.Error] * * Returns the value associated with @key under @group_name as an * integer. * - * If @key cannot be found then 0 is returned and @error is set to - * %G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated - * with @key cannot be interpreted as an integer, or is out of range - * for a #gint, then 0 is returned - * and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. + * If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. Likewise, if the value associated with @key cannot be interpreted + * as an integer, or is out of range for a `gint`, then + * [error@GLib.KeyFileError.INVALID_VALUE] is returned. * * Returns: the value associated with the key as an integer, or - * 0 if the key was not found or could not be parsed. + * `0` if the key was not found or could not be parsed. * * Since: 2.6 **/ @@ -2773,12 +2802,13 @@ g_key_file_get_integer (GKeyFile *key_file, /** * g_key_file_set_integer: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @value: an integer value * * Associates a new integer value with @key under @group_name. + * * If @key cannot be found then it is created. * * Since: 2.6 @@ -2800,17 +2830,19 @@ g_key_file_set_integer (GKeyFile *key_file, /** * g_key_file_get_int64: - * @key_file: a non-%NULL #GKeyFile - * @group_name: a non-%NULL group name - * @key: a non-%NULL key - * @error: return location for a #GError + * @key_file: a key file + * @group_name: a group name + * @key: a key + * @error: return location for a [struct@GLib.Error] * * Returns the value associated with @key under @group_name as a signed - * 64-bit integer. This is similar to g_key_file_get_integer() but can return + * 64-bit integer. + * + * This is similar to [method@GLib.KeyFile.get_integer] but can return * 64-bit results without truncation. * * Returns: the value associated with the key as a signed 64-bit integer, or - * 0 if the key was not found or could not be parsed. + * `0` if the key was not found or could not be parsed. * * Since: 2.26 */ @@ -2850,12 +2882,13 @@ g_key_file_get_int64 (GKeyFile *key_file, /** * g_key_file_set_int64: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @value: an integer value * * Associates a new integer value with @key under @group_name. + * * If @key cannot be found then it is created. * * Since: 2.26 @@ -2877,17 +2910,19 @@ g_key_file_set_int64 (GKeyFile *key_file, /** * g_key_file_get_uint64: - * @key_file: a non-%NULL #GKeyFile - * @group_name: a non-%NULL group name - * @key: a non-%NULL key - * @error: return location for a #GError + * @key_file: a key file + * @group_name: a group name + * @key: a key + * @error: return location for a [struct@GLib.Error] * * Returns the value associated with @key under @group_name as an unsigned - * 64-bit integer. This is similar to g_key_file_get_integer() but can return + * 64-bit integer. + * + * This is similar to [method@GLib.KeyFile.get_integer] but can return * large positive results without truncation. * * Returns: the value associated with the key as an unsigned 64-bit integer, - * or 0 if the key was not found or could not be parsed. + * or `0` if the key was not found or could not be parsed. * * Since: 2.26 */ @@ -2927,12 +2962,13 @@ g_key_file_get_uint64 (GKeyFile *key_file, /** * g_key_file_set_uint64: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @value: an integer value * * Associates a new integer value with @key under @group_name. + * * If @key cannot be found then it is created. * * Since: 2.26 @@ -2954,25 +2990,24 @@ g_key_file_set_uint64 (GKeyFile *key_file, /** * g_key_file_get_integer_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @length: (out): the number of integers returned - * @error: return location for a #GError + * @error: return location for a [struct@GLib.Error] * * Returns the values associated with @key under @group_name as * integers. * - * If @key cannot be found then %NULL is returned and @error is set to - * %G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated - * with @key cannot be interpreted as integers, or are out of range for - * #gint, then %NULL is returned - * and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. + * If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. Likewise, if the values associated with @key cannot be interpreted + * as integers, or are out of range for `gint`, then + * [error@GLib.KeyFileError.INVALID_VALUE] is returned. * * Returns: (array length=length) (element-type gint) (transfer container): - * the values associated with the key as a list of integers, or %NULL if + * the values associated with the key as a list of integers, or `NULL` if * the key was not found or could not be parsed. The returned list of - * integers should be freed with g_free() when no longer needed. + * integers should be freed with [func@GLib.free] when no longer needed. * * Since: 2.6 **/ @@ -3031,13 +3066,14 @@ g_key_file_get_integer_list (GKeyFile *key_file, /** * g_key_file_set_integer_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @list: (array length=length): an array of integer values * @length: number of integer values in @list * - * Associates a list of integer values with @key under @group_name. + * Associates a list of integer values with @key under @group_name. + * * If @key cannot be found then it is created. * * Since: 2.6 @@ -3074,21 +3110,19 @@ g_key_file_set_integer_list (GKeyFile *key_file, /** * g_key_file_get_double: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key - * @error: return location for a #GError + * @error: return location for a [struct@GLib.Error] * - * Returns the value associated with @key under @group_name as a - * double. If @group_name is %NULL, the start_group is used. + * Returns the value associated with @key under @group_name as a double. * - * If @key cannot be found then 0.0 is returned and @error is set to - * %G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated - * with @key cannot be interpreted as a double then 0.0 is returned - * and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. + * If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. Likewise, if the value associated with @key cannot be interpreted + * as a double then [error@GLib.KeyFileError.INVALID_VALUE] is returned. * * Returns: the value associated with the key as a double, or - * 0.0 if the key was not found or could not be parsed. + * `0.0` if the key was not found or could not be parsed. * * Since: 2.12 **/ @@ -3142,12 +3176,13 @@ g_key_file_get_double (GKeyFile *key_file, /** * g_key_file_set_double: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @value: a double value * * Associates a new double value with @key under @group_name. + * * If @key cannot be found then it is created. * * Since: 2.12 @@ -3168,24 +3203,23 @@ g_key_file_set_double (GKeyFile *key_file, /** * g_key_file_get_double_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @length: (out): the number of doubles returned - * @error: return location for a #GError + * @error: return location for a [struct@GLib.Error] * * Returns the values associated with @key under @group_name as * doubles. * - * If @key cannot be found then %NULL is returned and @error is set to - * %G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated - * with @key cannot be interpreted as doubles then %NULL is returned - * and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. + * If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is + * returned. Likewise, if the values associated with @key cannot be interpreted + * as doubles then [error@GLib.KeyFileError.INVALID_VALUE] is returned. * * Returns: (array length=length) (element-type gdouble) (transfer container): - * the values associated with the key as a list of doubles, or %NULL if the + * the values associated with the key as a list of doubles, or `NULL` if the * key was not found or could not be parsed. The returned list of doubles - * should be freed with g_free() when no longer needed. + * should be freed with [func@GLib.free] when no longer needed. * * Since: 2.12 **/ @@ -3244,14 +3278,15 @@ g_key_file_get_double_list (GKeyFile *key_file, /** * g_key_file_set_double_list: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key * @list: (array length=length): an array of double values * @length: number of double values in @list * - * Associates a list of double values with @key under - * @group_name. If @key cannot be found then it is created. + * Associates a list of double values with @key under @group_name. + * + * If @key cannot be found then it is created. * * Since: 2.12 **/ @@ -3440,22 +3475,22 @@ g_key_file_set_group_comment (GKeyFile *key_file, /** * g_key_file_set_comment: - * @key_file: a #GKeyFile - * @group_name: (nullable): a group name, or %NULL - * @key: (nullable): a key + * @key_file: a key file + * @group_name: (nullable): a group name, or `NULL` to write a top-level comment + * @key: (nullable): a key, or `NULL` to write a group comment * @comment: a comment - * @error: return location for a #GError + * @error: return location for a [struct@GLib.Error] * * Places a comment above @key from @group_name. * - * If @key is %NULL then @comment will be written above @group_name. - * If both @key and @group_name are %NULL, then @comment will be + * If @key is `NULL` then @comment will be written above @group_name. + * If both @key and @group_name are `NULL`, then @comment will be * written above the first group in the file. * - * Note that this function prepends a '#' comment marker to + * Note that this function prepends a `#` comment marker to * each line of @comment. * - * Returns: %TRUE if the comment was written, %FALSE otherwise + * Returns: true if the comment was written, false otherwise * * Since: 2.6 **/ @@ -3667,21 +3702,22 @@ g_key_file_get_top_comment (GKeyFile *key_file, /** * g_key_file_get_comment: - * @key_file: a #GKeyFile - * @group_name: (nullable): a group name, or %NULL - * @key: (nullable): a key - * @error: return location for a #GError + * @key_file: a key file + * @group_name: (nullable): a group name, or `NULL` to get a top-level comment + * @key: (nullable): a key, or `NULL` to get a group comment + * @error: return location for a [struct@GLib.Error] * * Retrieves a comment above @key from @group_name. - * If @key is %NULL then @comment will be read from above - * @group_name. If both @key and @group_name are %NULL, then + * + * If @key is `NULL` then @comment will be read from above + * @group_name. If both @key and @group_name are `NULL`, then * @comment will be read from above the first group in the file. * - * Note that the returned string does not include the '#' comment markers, + * Note that the returned string does not include the `#` comment markers, * but does include any whitespace after them (on each line). It includes * the line breaks between lines, but does not include the final line break. * - * Returns: a comment that should be freed with g_free() + * Returns: a comment that should be freed with [func@GLib.free] * * Since: 2.6 **/ @@ -3703,17 +3739,18 @@ g_key_file_get_comment (GKeyFile *key_file, /** * g_key_file_remove_comment: - * @key_file: a #GKeyFile - * @group_name: (nullable): a group name, or %NULL - * @key: (nullable): a key - * @error: return location for a #GError + * @key_file: a key file + * @group_name: (nullable): a group name, or `NULL` to get a top-level comment + * @key: (nullable): a key, or `NULL` to get a group comment + * @error: return location for a [struct@GLib.Error] * * Removes a comment above @key from @group_name. - * If @key is %NULL then @comment will be removed above @group_name. - * If both @key and @group_name are %NULL, then @comment will + * + * If @key is `NULL` then @comment will be removed above @group_name. + * If both @key and @group_name are `NULL`, then @comment will * be removed above the first group in the file. * - * Returns: %TRUE if the comment was removed, %FALSE otherwise + * Returns: true if the comment was removed, false otherwise * * Since: 2.6 **/ @@ -3736,13 +3773,12 @@ g_key_file_remove_comment (GKeyFile *key_file, /** * g_key_file_has_group: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * * Looks whether the key file has the group @group_name. * - * Returns: %TRUE if @group_name is a part of @key_file, %FALSE - * otherwise. + * Returns: true if @group_name is a part of @key_file, false otherwise. * Since: 2.6 **/ gboolean @@ -3793,23 +3829,24 @@ g_key_file_has_key_full (GKeyFile *key_file, /** * g_key_file_has_key: (skip) - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key name - * @error: return location for a #GError + * @error: return location for a [struct@GLib.Error] * * Looks whether the key file has the key @key in the group * @group_name. * - * Note that this function does not follow the rules for #GError strictly; + * Note that this function does not follow the rules for [struct@GLib.Error] + * strictly; * the return value both carries meaning and signals an error. To use - * this function, you must pass a #GError pointer in @error, and check - * whether it is not %NULL to see if an error occurred. + * this function, you must pass a [struct@GLib.Error] pointer in @error, and + * check whether it is not `NULL` to see if an error occurred. * - * Language bindings should use g_key_file_get_value() to test whether - * or not a key exists. + * Language bindings should use [method@GLib.KeyFile.get_value] to test whether + * a key exists. * - * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise + * Returns: true if @key is a part of @group_name, false otherwise * * Since: 2.6 **/ @@ -4000,14 +4037,14 @@ g_key_file_remove_group_node (GKeyFile *key_file, /** * g_key_file_remove_group: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name - * @error: return location for a #GError or %NULL + * @error: return location for a [struct@GLib.Error] * * Removes the specified group, @group_name, * from the key file. * - * Returns: %TRUE if the group was removed, %FALSE otherwise + * Returns: true if the group was removed, false otherwise * * Since: 2.6 **/ @@ -4070,14 +4107,14 @@ g_key_file_add_key (GKeyFile *key_file, /** * g_key_file_remove_key: - * @key_file: a #GKeyFile + * @key_file: a key file * @group_name: a group name * @key: a key name to remove - * @error: return location for a #GError or %NULL + * @error: return location for a [struct@GLib.Error] * * Removes @key in @group_name from the key file. * - * Returns: %TRUE if the key was removed, %FALSE otherwise + * Returns: true if the key was removed, false otherwise * * Since: 2.6 **/ @@ -4690,19 +4727,22 @@ g_key_file_parse_comment_as_value (GKeyFile *key_file, /** * g_key_file_save_to_file: - * @key_file: a #GKeyFile + * @key_file: a key file * @filename: the name of the file to write to - * @error: a pointer to a %NULL #GError, or %NULL + * @error: return location for a [struct@GLib.Error] * * Writes the contents of @key_file to @filename using - * g_file_set_contents(). If you need stricter guarantees about durability of - * the written file than are provided by g_file_set_contents(), use - * g_file_set_contents_full() with the return value of g_key_file_to_data(). + * [func@GLib.file_set_contents]. + * + * If you need stricter guarantees about durability of + * the written file than are provided by [func@GLib.file_set_contents], use + * [func@GLib.file_set_contents_full] with the return value of + * [method@GLib.KeyFile.to_data]. * * This function can fail for any of the reasons that - * g_file_set_contents() may fail. + * [func@GLib.file_set_contents] may fail. * - * Returns: %TRUE if successful, else %FALSE with @error set + * Returns: true if successful, false otherwise * * Since: 2.40 */