diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml index b01133900..b1537baf6 100644 --- a/docs/reference/gio/gio-docs.xml +++ b/docs/reference/gio/gio-docs.xml @@ -48,8 +48,8 @@ Data conversion - - + + Streaming I/O diff --git a/docs/reference/gio/gio-sections-common.txt b/docs/reference/gio/gio-sections-common.txt index 1b1ddc531..137737260 100644 --- a/docs/reference/gio/gio-sections-common.txt +++ b/docs/reference/gio/gio-sections-common.txt @@ -2505,7 +2505,7 @@ g_converter_output_stream_get_type
-gzcompressor +gzlibcompressor GZlibCompressor GZlibCompressor GZlibCompressorFormat @@ -2527,7 +2527,7 @@ g_zlib_compressor_format_get_type
-gzdecompressor +gzlibdecompressor GZlibDecompressor GZlibDecompressor g_zlib_decompressor_new diff --git a/gio/gfileinfo.h b/gio/gfileinfo.h index 4f736e487..086dda032 100644 --- a/gio/gfileinfo.h +++ b/gio/gfileinfo.h @@ -49,7 +49,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_TYPE: * * A key in the "standard" namespace for storing file types. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * * The value for this key should contain a #GFileType. **/ #define G_FILE_ATTRIBUTE_STANDARD_TYPE "standard::type" /* uint32 (GFileType) */ @@ -58,6 +60,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN: * * A key in the "standard" namespace for checking if a file is hidden. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN "standard::is-hidden" /* boolean */ @@ -66,6 +69,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP: * * A key in the "standard" namespace for checking if a file is a backup file. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP "standard::is-backup" /* boolean */ @@ -76,7 +80,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * A key in the "standard" namespace for checking if the file is a symlink. * Typically the actual type is something else, if we followed the symlink * to get the type. + * * On Windows NTFS mountpoints are considered to be symlinks as well. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK "standard::is-symlink" /* boolean */ @@ -85,6 +91,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL: * * A key in the "standard" namespace for checking if a file is virtual. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL "standard::is-virtual" /* boolean */ @@ -95,7 +102,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * A key in the "standard" namespace for checking if a file is * volatile. This is meant for opaque, non-POSIX-like backends to * indicate that the URI is not persistent. Applications should look - * at #G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI. + * at %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI. * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * @@ -107,11 +114,14 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_NAME: * * A key in the "standard" namespace for getting the name of the file. + * * The name is the on-disk filename which may not be in any known encoding, * and can thus not be generally displayed as is. It is guaranteed to be set on * every file. - * Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the + * + * Use %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the * name in a user interface. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. **/ #define G_FILE_ATTRIBUTE_STANDARD_NAME "standard::name" /* byte string */ @@ -120,8 +130,10 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME: * * A key in the "standard" namespace for getting the display name of the file. + * * A display name is guaranteed to be in UTF-8 and can thus be displayed in * the UI. It is guaranteed to be set on every file. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME "standard::display-name" /* string */ @@ -130,6 +142,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME: * * A key in the "standard" namespace for edit name of the file. + * * An edit name is similar to the display name, but it is meant to be * used when you want to rename the file in the UI. The display name * might contain information you don't want in the new filename (such as @@ -143,6 +156,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_COPY_NAME: * * A key in the "standard" namespace for getting the copy name of the file. + * * The copy name is an optional version of the name. If available it's always * in UTF8, and corresponds directly to the original filename (only transcoded to * UTF8). This is useful if you want to copy the file to another filesystem that @@ -157,6 +171,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION: * * A key in the "standard" namespace for getting the description of the file. + * * The description is a utf8 string that describes the file, generally containing * the filename, but can also contain further information. Example descriptions * could be "filename (on hostname)" for a remote file or "filename (in trash)" @@ -171,7 +186,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_ICON: * * A key in the "standard" namespace for getting the icon for the file. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. + * * The value for this key should contain a #GIcon. **/ #define G_FILE_ATTRIBUTE_STANDARD_ICON "standard::icon" /* object (GIcon) */ @@ -180,7 +197,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON: * * A key in the "standard" namespace for getting the symbolic icon for the file. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. + * * The value for this key should contain a #GIcon. * * Since: 2.34 @@ -191,7 +210,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE: * * A key in the "standard" namespace for getting the content type of the file. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * * The value for this key should contain a valid content type. **/ #define G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE "standard::content-type" /* string */ @@ -200,9 +221,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE: * * A key in the "standard" namespace for getting the fast content type. + * * The fast content type isn't as reliable as the regular one, as it * only uses the filename to guess it, but it is faster to calculate than the * regular content type. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * **/ @@ -212,6 +235,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_SIZE: * * A key in the "standard" namespace for getting the file's size (in bytes). + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. **/ #define G_FILE_ATTRIBUTE_STANDARD_SIZE "standard::size" /* uint64 */ @@ -220,9 +244,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE: * * A key in the "standard" namespace for getting the amount of disk space - * that is consumed by the file (in bytes). This will generally be larger - * than the file size (due to block size overhead) but can occasionally be - * smaller (for example, for sparse files). + * that is consumed by the file (in bytes). + * + * This will generally be larger than the file size (due to block size + * overhead) but can occasionally be smaller (for example, for sparse files). + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. * * Since: 2.20 @@ -233,8 +259,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET: * * A key in the "standard" namespace for getting the symlink target, if the file - * is a symlink. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + * is a symlink. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. **/ #define G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET "standard::symlink-target" /* byte string */ @@ -243,6 +270,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * * A key in the "standard" namespace for getting the target URI for the file, in * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_STANDARD_TARGET_URI "standard::target-uri" /* string */ @@ -251,7 +279,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER: * * A key in the "standard" namespace for setting the sort order of a file. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. + * * An example use would be in file managers, which would use this key * to set the order files are displayed. Files with smaller sort order * should be sorted first, and files without sort order as if sort order @@ -265,8 +295,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ETAG_VALUE: * * A key in the "etag" namespace for getting the value of the file's - * entity tag. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. + * entity tag. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_ETAG_VALUE "etag::value" /* string */ @@ -278,7 +309,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ID_FILE: * * A key in the "id" namespace for getting a file identifier. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * * An example use would be during listing files, to avoid recursive * directory scanning. **/ @@ -288,7 +321,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ID_FILESYSTEM: * * A key in the "id" namespace for getting the file system identifier. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * * An example use would be during drag and drop to see if the source * and target are on the same filesystem (default to move) or not (default * to copy). @@ -301,7 +336,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ACCESS_CAN_READ: * * A key in the "access" namespace for getting read privileges. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * * This attribute will be %TRUE if the user is able to read the file. **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_READ "access::can-read" /* boolean */ @@ -310,7 +347,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE: * * A key in the "access" namespace for getting write privileges. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * * This attribute will be %TRUE if the user is able to write to the file. **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE "access::can-write" /* boolean */ @@ -319,7 +358,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE: * * A key in the "access" namespace for getting execution privileges. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * * This attribute will be %TRUE if the user is able to execute the file. **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE "access::can-execute" /* boolean */ @@ -328,7 +369,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE: * * A key in the "access" namespace for checking deletion privileges. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * * This attribute will be %TRUE if the user is able to delete the file. **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE "access::can-delete" /* boolean */ @@ -337,7 +380,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH: * * A key in the "access" namespace for checking trashing privileges. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * * This attribute will be %TRUE if the user is able to move the file to * the trash. **/ @@ -347,7 +392,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME: * * A key in the "access" namespace for checking renaming privileges. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * * This attribute will be %TRUE if the user is able to rename the file. **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME "access::can-rename" /* boolean */ @@ -359,7 +406,9 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. + * A key in the "mountable" namespace for checking if a file (of + * type G_FILE_TYPE_MOUNTABLE) is mountable. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT "mountable::can-mount" /* boolean */ @@ -367,7 +416,9 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. + * A key in the "mountable" namespace for checking if a file (of + * type G_FILE_TYPE_MOUNTABLE) is unmountable. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT "mountable::can-unmount" /* boolean */ @@ -375,7 +426,9 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. + * A key in the "mountable" namespace for checking if a file (of + * type G_FILE_TYPE_MOUNTABLE) can be ejected. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT "mountable::can-eject" /* boolean */ @@ -384,6 +437,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE: * * A key in the "mountable" namespace for getting the unix device. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE "mountable::unix-device" /* uint32 */ @@ -392,6 +446,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE: * * A key in the "mountable" namespace for getting the unix device file. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * * Since: 2.22 @@ -402,14 +457,18 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI: * * A key in the "mountable" namespace for getting the HAL UDI for the mountable - * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * file. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI "mountable::hal-udi" /* string */ /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started. + * A key in the "mountable" namespace for checking if a file (of + * type G_FILE_TYPE_MOUNTABLE) can be started. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * * Since: 2.22 @@ -419,8 +478,9 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started - * degraded. + * A key in the "mountable" namespace for checking if a file (of + * type G_FILE_TYPE_MOUNTABLE) can be started degraded. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * * Since: 2.22 @@ -430,7 +490,9 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped. + * A key in the "mountable" namespace for checking if a file (of + * type G_FILE_TYPE_MOUNTABLE) can be stopped. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * * Since: 2.22 @@ -441,6 +503,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE: * * A key in the "mountable" namespace for getting the #GDriveStartStopType. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * * Since: 2.22 @@ -450,7 +513,9 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled. + * A key in the "mountable" namespace for checking if a file (of + * type G_FILE_TYPE_MOUNTABLE) can be polled. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * * Since: 2.22 @@ -460,8 +525,9 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) - * is automatically polled for media. + * A key in the "mountable" namespace for checking if a file (of + * type G_FILE_TYPE_MOUNTABLE) is automatically polled for media. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * * Since: 2.22 @@ -474,9 +540,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_TIME_MODIFIED: * * A key in the "time" namespace for getting the time the file was last - * modified. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the - * file was modified, in seconds since the UNIX epoch. + * modified. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and + * contains the time since the file was modified, in seconds since the UNIX + * epoch. **/ #define G_FILE_ATTRIBUTE_TIME_MODIFIED "time::modified" /* uint64 */ @@ -484,9 +552,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC: * * A key in the "time" namespace for getting the microseconds of the time - * the file was last modified. This should be used in conjunction with - * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * the file was last modified. + * + * This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_MODIFIED. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC "time::modified-usec" /* uint32 */ @@ -494,9 +564,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_TIME_ACCESS: * * A key in the "time" namespace for getting the time the file was last - * accessed. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the - * file was last accessed, in seconds since the UNIX epoch. + * accessed. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and + * contains the time since the file was last accessed, in seconds since the + * UNIX epoch. **/ #define G_FILE_ATTRIBUTE_TIME_ACCESS "time::access" /* uint64 */ @@ -504,9 +576,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC: * * A key in the "time" namespace for getting the microseconds of the time - * the file was last accessed. This should be used in conjunction with - * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * the file was last accessed. + * + * This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_ACCESS. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_TIME_ACCESS_USEC "time::access-usec" /* uint32 */ @@ -514,9 +588,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_TIME_CHANGED: * * A key in the "time" namespace for getting the time the file was last - * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, - * and contains the time since the file was last changed, in seconds since the - * UNIX epoch. + * changed. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, + * and contains the time since the file was last changed, in seconds since + * the UNIX epoch. * * This corresponds to the traditional UNIX ctime. **/ @@ -526,9 +602,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC: * * A key in the "time" namespace for getting the microseconds of the time - * the file was last changed. This should be used in conjunction with - * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * the file was last changed. + * + * This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CHANGED. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_TIME_CHANGED_USEC "time::changed-usec" /* uint32 */ @@ -536,12 +614,13 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_TIME_CREATED: * * A key in the "time" namespace for getting the time the file was created. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, * and contains the time since the file was created, in seconds since the UNIX * epoch. * - * This may correspond to Linux stx_btime, FreeBSD st_birthtim, NetBSD - * st_birthtime or NTFS ctime. + * This may correspond to Linux `stx_btime`, FreeBSD `st_birthtim`, NetBSD + * `st_birthtime` or NTFS `ctime`. **/ #define G_FILE_ATTRIBUTE_TIME_CREATED "time::created" /* uint64 */ @@ -549,9 +628,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_TIME_CREATED_USEC: * * A key in the "time" namespace for getting the microseconds of the time - * the file was created. This should be used in conjunction with - * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * the file was created. + * + * This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CREATED. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_TIME_CREATED_USEC "time::created-usec" /* uint32 */ @@ -561,9 +642,11 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_DEVICE: * * A key in the "unix" namespace for getting the device id of the device the - * file is located on (see stat() documentation). This attribute is only - * available for UNIX file systems. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * file is located on (see stat() documentation). + * + * This attribute is only available for UNIX file systems. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_UNIX_DEVICE "unix::device" /* uint32 */ @@ -571,8 +654,10 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_INODE: * * A key in the "unix" namespace for getting the inode of the file. - * This attribute is only available for UNIX file systems. Corresponding - * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + * + * This attribute is only available for UNIX file systems. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. **/ #define G_FILE_ATTRIBUTE_UNIX_INODE "unix::inode" /* uint64 */ @@ -580,10 +665,14 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_MODE: * * A key in the "unix" namespace for getting the mode of the file - * (e.g. whether the file is a regular file, symlink, etc). See the - * documentation for `lstat()`: this attribute is equivalent to the `st_mode` - * member of `struct stat`, and includes both the file type and permissions. + * (e.g. whether the file is a regular file, symlink, etc). + * + * See the documentation for `lstat()`: this attribute is equivalent to + * the `st_mode` member of `struct stat`, and includes both the file type + * and permissions. + * * This attribute is only available for UNIX file systems. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_UNIX_MODE "unix::mode" /* uint32 */ @@ -592,9 +681,13 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_NLINK: * * A key in the "unix" namespace for getting the number of hard links - * for a file. See lstat() documentation. This attribute is only available - * for UNIX file systems. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * for a file. + * + * See the documentation for `lstat()`. + * + * This attribute is only available for UNIX file systems. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_UNIX_NLINK "unix::nlink" /* uint32 */ @@ -602,7 +695,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_UID: * * A key in the "unix" namespace for getting the user ID for the file. + * * This attribute is only available for UNIX file systems. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_UNIX_UID "unix::uid" /* uint32 */ @@ -611,7 +706,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_GID: * * A key in the "unix" namespace for getting the group ID for the file. + * * This attribute is only available for UNIX file systems. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_UNIX_GID "unix::gid" /* uint32 */ @@ -620,9 +717,13 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_RDEV: * * A key in the "unix" namespace for getting the device ID for the file - * (if it is a special file). See lstat() documentation. This attribute - * is only available for UNIX file systems. Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * (if it is a special file). + * + * See the documentation for `lstat()`. + * + * This attribute is only available for UNIX file systems. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_UNIX_RDEV "unix::rdev" /* uint32 */ @@ -630,7 +731,10 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE: * * A key in the "unix" namespace for getting the block size for the file - * system. This attribute is only available for UNIX file systems. + * system. + * + * This attribute is only available for UNIX file systems. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE "unix::block-size" /* uint32 */ @@ -639,7 +743,10 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_BLOCKS: * * A key in the "unix" namespace for getting the number of blocks allocated - * for the file. This attribute is only available for UNIX file systems. + * for the file. + * + * This attribute is only available for UNIX file systems. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. **/ #define G_FILE_ATTRIBUTE_UNIX_BLOCKS "unix::blocks" /* uint64 */ @@ -648,9 +755,14 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT: * * A key in the "unix" namespace for checking if the file represents a - * UNIX mount point. This attribute is %TRUE if the file is a UNIX mount - * point. Since 2.58, `/` is considered to be a mount point. + * UNIX mount point. + * + * This attribute is %TRUE if the file is a UNIX mount point. + * + * Since 2.58, `/` is considered to be a mount point. + * * This attribute is only available for UNIX file systems. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT "unix::is-mountpoint" /* boolean */ @@ -661,9 +773,13 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE: * * A key in the "dos" namespace for checking if the file's archive flag - * is set. This attribute is %TRUE if the archive flag is set. This attribute - * is only available for DOS file systems. Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * is set. + * + * This attribute is %TRUE if the archive flag is set. + * + * This attribute is only available for DOS file systems. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE "dos::is-archive" /* boolean */ @@ -671,9 +787,13 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM: * * A key in the "dos" namespace for checking if the file's backup flag - * is set. This attribute is %TRUE if the backup flag is set. This attribute - * is only available for DOS file systems. Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * is set. + * + * This attribute is %TRUE if the backup flag is set. + * + * This attribute is only available for DOS file systems. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_DOS_IS_SYSTEM "dos::is-system" /* boolean */ @@ -682,9 +802,12 @@ typedef struct _GFileInfoClass GFileInfoClass; * * A key in the "dos" namespace for checking if the file is a NTFS mount point * (a volume mount or a junction point). + * * This attribute is %TRUE if file is a reparse point of type * [IO_REPARSE_TAG_MOUNT_POINT](https://msdn.microsoft.com/en-us/library/dd541667.aspx). + * * This attribute is only available for DOS file systems. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * * Since: 2.60 @@ -695,10 +818,13 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_DOS_REPARSE_POINT_TAG: * * A key in the "dos" namespace for getting the file NTFS reparse tag. + * * This value is 0 for files that are not reparse points. + * * See the [Reparse Tags](https://msdn.microsoft.com/en-us/library/dd541667.aspx) - * page for possible reparse tag values. Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * page for possible reparse tag values. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * * Since: 2.60 **/ @@ -710,8 +836,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_OWNER_USER: * * A key in the "owner" namespace for getting the user name of the - * file's owner. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. + * file's owner. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_OWNER_USER "owner::user" /* string */ @@ -719,8 +846,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_OWNER_USER_REAL: * * A key in the "owner" namespace for getting the real name of the - * user that owns the file. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. + * user that owns the file. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_OWNER_USER_REAL "owner::user-real" /* string */ @@ -728,6 +856,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_OWNER_GROUP: * * A key in the "owner" namespace for getting the file owner's group. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_OWNER_GROUP "owner::group" /* string */ @@ -738,22 +867,26 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_THUMBNAIL_PATH: * * A key in the "thumbnail" namespace for getting the path to the thumbnail - * image. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + * image. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. **/ #define G_FILE_ATTRIBUTE_THUMBNAIL_PATH "thumbnail::path" /* bytestring */ /** * G_FILE_ATTRIBUTE_THUMBNAILING_FAILED: * * A key in the "thumbnail" namespace for checking if thumbnailing failed. - * This attribute is %TRUE if thumbnailing failed. Corresponding - * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * + * This attribute is %TRUE if thumbnailing failed. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_THUMBNAILING_FAILED "thumbnail::failed" /* boolean */ /** * G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID: * * A key in the "thumbnail" namespace for checking whether the thumbnail is outdated. + * * This attribute is %TRUE if the thumbnail is up-to-date with the file it represents, * and %FALSE if the file has been modified since the thumbnail was generated. * @@ -772,10 +905,13 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_PREVIEW_ICON: * * A key in the "preview" namespace for getting a #GIcon that can be - * used to get preview of the file. For example, it may be a low - * resolution thumbnail without metadata. Corresponding - * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value - * for this key should contain a #GIcon. + * used to get preview of the file. + * + * For example, it may be a low resolution thumbnail without metadata. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. + * + * The value for this key should contain a #GIcon. * * Since: 2.20 **/ @@ -786,27 +922,30 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_FILESYSTEM_SIZE: * - * A key in the "filesystem" namespace for getting the total size (in bytes) of the file system, - * used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_UINT64. + * A key in the "filesystem" namespace for getting the total size (in + * bytes) of the file system, used in g_file_query_filesystem_info(). + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. **/ #define G_FILE_ATTRIBUTE_FILESYSTEM_SIZE "filesystem::size" /* uint64 */ /** * G_FILE_ATTRIBUTE_FILESYSTEM_FREE: * - * A key in the "filesystem" namespace for getting the number of bytes of free space left on the - * file system. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT64. + * A key in the "filesystem" namespace for getting the number of bytes + * of free space left on the file system. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. **/ #define G_FILE_ATTRIBUTE_FILESYSTEM_FREE "filesystem::free" /* uint64 */ /** * G_FILE_ATTRIBUTE_FILESYSTEM_USED: * - * A key in the "filesystem" namespace for getting the number of bytes of used on the - * file system. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT64. + * A key in the "filesystem" namespace for getting the number of bytes + * used by data on the file system. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. * * Since: 2.32 */ @@ -816,6 +955,7 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_FILESYSTEM_TYPE: * * A key in the "filesystem" namespace for getting the file system's type. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_FILESYSTEM_TYPE "filesystem::type" /* string */ @@ -824,7 +964,10 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_FILESYSTEM_READONLY: * * A key in the "filesystem" namespace for checking if the file system - * is read only. Is set to %TRUE if the file system is read only. + * is read only. + * + * Is set to %TRUE if the file system is read only. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_FILESYSTEM_READONLY "filesystem::readonly" /* boolean */ @@ -834,8 +977,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * * A key in the "filesystem" namespace for hinting a file manager * application whether it should preview (e.g. thumbnail) files on the - * file system. The value for this key contain a - * #GFilesystemPreviewType. + * file system. + * + * The value for this key contain a #GFilesystemPreviewType. **/ #define G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW "filesystem::use-preview" /* uint32 (GFilesystemPreviewType) */ @@ -843,7 +987,10 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_FILESYSTEM_REMOTE: * * A key in the "filesystem" namespace for checking if the file system - * is remote. Is set to %TRUE if the file system is remote. + * is remote. + * + * Is set to %TRUE if the file system is remote. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_FILESYSTEM_REMOTE "filesystem::remote" /* boolean */ @@ -852,8 +999,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_GVFS_BACKEND: * * A key in the "gvfs" namespace that gets the name of the current - * GVFS backend in use. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. + * GVFS backend in use. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_GVFS_BACKEND "gvfs::backend" /* string */ @@ -861,17 +1009,21 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_SELINUX_CONTEXT: * * A key in the "selinux" namespace for getting the file's SELinux - * context. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only - * available if GLib has been built with SELinux support. + * context. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * + * Note that this attribute is only available if GLib has been built + * with SELinux support. **/ #define G_FILE_ATTRIBUTE_SELINUX_CONTEXT "selinux::context" /* string */ /** * G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT: * - * A key in the "trash" namespace. When requested against - * `trash:///` returns the number of (toplevel) items in the trash folder. + * A key in the "trash" namespace for getting the number of (toplevel) items + * that are present in the `trash:///` folder. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. **/ #define G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT "trash::item-count" /* uint32 */ @@ -879,10 +1031,10 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_TRASH_ORIG_PATH: * - * A key in the "trash" namespace. When requested against - * items in `trash:///`, will return the original path to the file before it - * was trashed. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + * A key in the "trash" namespace for getting the original path of a file + * inside the `trash:///` folder before it was trashed. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. * * Since: 2.24 **/ @@ -891,9 +1043,11 @@ typedef struct _GFileInfoClass GFileInfoClass; /** * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE: * - * A key in the "trash" namespace. When requested against - * items in `trash:///`, will return the date and time when the file - * was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss. + * A key in the "trash" namespace for getting the deletion date and time + * of a file inside the `trash:///` folder. + * + * The format of the returned string is `YYYY-MM-DDThh:mm:ss`. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * * Since: 2.24 @@ -904,8 +1058,9 @@ typedef struct _GFileInfoClass GFileInfoClass; * G_FILE_ATTRIBUTE_RECENT_MODIFIED: * * A key in the "recent" namespace for getting time, when the metadata for the - * file in `recent:///` was last changed. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_INT64. + * file in `recent:///` was last changed. + * + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT64. * * Since: 2.52 **/ diff --git a/gio/gmemorymonitor.c b/gio/gmemorymonitor.c index 37ddf48ca..cef89f7fe 100644 --- a/gio/gmemorymonitor.c +++ b/gio/gmemorymonitor.c @@ -42,13 +42,14 @@ * There is also an implementation for use inside Flatpak sandboxes. * * Possible actions to take when the signal is received are: - * - Free caches - * - Save files that haven't been looked at in a while to disk, ready to be reopened when needed - * - Run a garbage collection cycle - * - Try and compress fragmented allocations - * - Exit on idle if the process has no reason to stay around - * - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to - * the kernel (if supported by your libc) + * + * - Free caches + * - Save files that haven't been looked at in a while to disk, ready to be reopened when needed + * - Run a garbage collection cycle + * - Try and compress fragmented allocations + * - Exit on idle if the process has no reason to stay around + * - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to + * the kernel (if supported by your libc) * * Note that some actions may not always improve system performance, and so * should be profiled for your application. `malloc_trim()`, for example, may diff --git a/gio/gzlibcompressor.c b/gio/gzlibcompressor.c index b68f8823a..6d4ef5003 100644 --- a/gio/gzlibcompressor.c +++ b/gio/gzlibcompressor.c @@ -41,7 +41,7 @@ enum { }; /** - * SECTION:gzcompressor + * SECTION:gzlibcompressor * @short_description: Zlib compressor * @include: gio/gio.h * diff --git a/gio/gzlibdecompressor.c b/gio/gzlibdecompressor.c index e3f225150..8e54812e4 100644 --- a/gio/gzlibdecompressor.c +++ b/gio/gzlibdecompressor.c @@ -40,7 +40,7 @@ enum { }; /** - * SECTION:gzdecompressor + * SECTION:gzlibdecompressor * @short_description: Zlib decompressor * @include: gio/gio.h * diff --git a/glib/gasyncqueue.c b/glib/gasyncqueue.c index db053f399..98c7d8a60 100644 --- a/glib/gasyncqueue.c +++ b/glib/gasyncqueue.c @@ -88,9 +88,9 @@ /** * GAsyncQueue: * - * The GAsyncQueue struct is an opaque data structure which represents - * an asynchronous queue. It should only be accessed through the - * g_async_queue_* functions. + * An opaque data structure which represents an asynchronous queue. + * + * It should only be accessed through the `g_async_queue_*` functions. */ struct _GAsyncQueue { diff --git a/glib/gbookmarkfile.h b/glib/gbookmarkfile.h index e9cfbf12b..82ea98d5d 100644 --- a/glib/gbookmarkfile.h +++ b/glib/gbookmarkfile.h @@ -33,6 +33,7 @@ G_BEGIN_DECLS * G_BOOKMARK_FILE_ERROR: * * Error domain for bookmark file parsing. + * * Errors in this domain will be from the #GBookmarkFileError * enumeration. See #GError for information on error domains. */ @@ -72,8 +73,7 @@ GQuark g_bookmark_file_error_quark (void); /** * GBookmarkFile: * - * The `GBookmarkFile` structure contains only - * private data and should not be directly accessed. + * An opaque data structure representing a set of bookmarks. */ typedef struct _GBookmarkFile GBookmarkFile; diff --git a/glib/gchecksum.h b/glib/gchecksum.h index 599f439c1..5bb52d824 100644 --- a/glib/gchecksum.h +++ b/glib/gchecksum.h @@ -56,6 +56,7 @@ typedef enum { * GChecksum: * * An opaque structure representing a checksumming operation. + * * To create a new GChecksum, use g_checksum_new(). To free * a GChecksum, use g_checksum_free(). * diff --git a/glib/gdataset.c b/glib/gdataset.c index bfff3e009..793e21f8b 100644 --- a/glib/gdataset.c +++ b/glib/gdataset.c @@ -121,9 +121,9 @@ /** * GData: * - * The #GData struct is an opaque data structure to represent a - * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be - * accessed via the following functions. + * An opaque data structure that represents a keyed data list. + * + * See also: [Keyed data lists][glib-Keyed-Data-Lists]. **/ /** diff --git a/glib/gdate.c b/glib/gdate.c index 6b36ae718..59a85c4f6 100644 --- a/glib/gdate.c +++ b/glib/gdate.c @@ -115,7 +115,8 @@ * @tv_usec: microseconds * * Represents a precise time, with seconds and microseconds. - * Similar to the struct timeval returned by the gettimeofday() + * + * Similar to the struct timeval returned by the `gettimeofday()` * UNIX system call. * * GLib is attempting to unify around the use of 64-bit integers to @@ -133,15 +134,15 @@ * @julian: this bit is set if @julian_days is valid * @dmy: this is set if @day, @month and @year are valid * @day: the day of the day-month-year representation of the date, - * as a number between 1 and 31 + * as a number between 1 and 31 * @month: the day of the day-month-year representation of the date, - * as a number between 1 and 12 + * as a number between 1 and 12 * @year: the day of the day-month-year representation of the date * * Represents a day between January 1, Year 1 and a few thousand years in * the future. None of its members should be accessed directly. * - * If the #GDate-struct is obtained from g_date_new(), it will be safe + * If the `GDate` is obtained from g_date_new(), it will be safe * to mutate but invalid and thus not safe for calendrical computations. * * If it's declared on the stack, it will contain garbage so must be @@ -156,7 +157,9 @@ * * Simply a replacement for `time_t`. It has been deprecated * since it is not equivalent to `time_t` on 64-bit platforms - * with a 64-bit `time_t`. Unrelated to #GTimer. + * with a 64-bit `time_t`. + * + * Unrelated to #GTimer. * * Note that #GTime is defined to always be a 32-bit integer, * unlike `time_t` which may be 64-bit on some systems. Therefore, @@ -165,6 +168,7 @@ * function. * * Instead, do the following: + * * |[ * time_t ttime; * GTime gtime; @@ -191,7 +195,8 @@ * GDateDay: * * Integer representing a day of the month; between 1 and 31. - * #G_DATE_BAD_DAY represents an invalid day of the month. + * + * The %G_DATE_BAD_DAY value represents an invalid day of the month. */ /** @@ -210,16 +215,20 @@ * @G_DATE_NOVEMBER: November * @G_DATE_DECEMBER: December * - * Enumeration representing a month; values are #G_DATE_JANUARY, - * #G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value. + * Enumeration representing a month; values are %G_DATE_JANUARY, + * %G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value. */ /** * GDateYear: * - * Integer representing a year; #G_DATE_BAD_YEAR is the invalid - * value. The year must be 1 or higher; negative (BC) years are not - * allowed. The year is represented with four digits. + * Integer type representing a year. + * + * The %G_DATE_BAD_YEAR value is the invalid value. The year + * must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era)) + * years are not allowed. + * + * The year is represented with four digits. */ /** diff --git a/glib/gdatetime.h b/glib/gdatetime.h index fa43d8531..4e1afdf9b 100644 --- a/glib/gdatetime.h +++ b/glib/gdatetime.h @@ -89,8 +89,7 @@ typedef gint64 GTimeSpan; /** * GDateTime: * - * `GDateTime` is an opaque structure whose members - * cannot be accessed directly. + * An opaque structure that represents a date and time, including a time zone. * * Since: 2.26 */ diff --git a/glib/gfileutils.c b/glib/gfileutils.c index e0a2a65d0..2a0db4f97 100644 --- a/glib/gfileutils.c +++ b/glib/gfileutils.c @@ -502,15 +502,16 @@ G_DEFINE_QUARK (g-file-error-quark, g_file_error) * @err_no: an "errno" value * * Gets a #GFileError constant based on the passed-in @err_no. + * * For example, if you pass in `EEXIST` this function returns - * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably + * %G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably * assume that all #GFileError values will exist. * * Normally a #GFileError value goes into a #GError returned * from a function that manipulates files. So you would use * g_file_error_from_errno() when constructing a #GError. * - * Returns: #GFileError corresponding to the given @errno + * Returns: #GFileError corresponding to the given @err_no **/ GFileError g_file_error_from_errno (gint err_no) diff --git a/glib/gfileutils.h b/glib/gfileutils.h index d6b1d9eec..4c9633224 100644 --- a/glib/gfileutils.h +++ b/glib/gfileutils.h @@ -75,21 +75,21 @@ typedef enum /** * GFileSetContentsFlags: * @G_FILE_SET_CONTENTS_NONE: No guarantees about file consistency or durability. - * The most dangerous setting, which is slightly faster than other settings. + * The most dangerous setting, which is slightly faster than other settings. * @G_FILE_SET_CONTENTS_CONSISTENT: Guarantee file consistency: after a crash, - * either the old version of the file or the new version of the file will be - * available, but not a mixture. On Unix systems this equates to an `fsync()` - * on the file and use of an atomic `rename()` of the new version of the file - * over the old. + * either the old version of the file or the new version of the file will be + * available, but not a mixture. On Unix systems this equates to an `fsync()` + * on the file and use of an atomic `rename()` of the new version of the file + * over the old. * @G_FILE_SET_CONTENTS_DURABLE: Guarantee file durability: after a crash, the - * new version of the file will be available. On Unix systems this equates to - * an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or - * the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the - * directory containing the file after calling `rename()`. + * new version of the file will be available. On Unix systems this equates to + * an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or + * the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the + * directory containing the file after calling `rename()`. * @G_FILE_SET_CONTENTS_ONLY_EXISTING: Only apply consistency and durability - * guarantees if the file already exists. This may speed up file operations - * if the file doesn’t currently exist, but may result in a corrupted version - * of the new file if the system crashes while writing it. + * guarantees if the file already exists. This may speed up file operations + * if the file doesn’t currently exist, but may result in a corrupted version + * of the new file if the system crashes while writing it. * * Flags to pass to g_file_set_contents_full() to affect its safety and * performance. diff --git a/glib/gkeyfile.c b/glib/gkeyfile.c index 0b58edb3f..56500ccce 100644 --- a/glib/gkeyfile.c +++ b/glib/gkeyfile.c @@ -218,7 +218,7 @@ /** * GKeyFileError: * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in - * an unknown encoding + * an unknown encoding * @G_KEY_FILE_ERROR_PARSE: document was ill-formed * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found @@ -232,13 +232,13 @@ * GKeyFileFlags: * @G_KEY_FILE_NONE: No flags, default behaviour * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the - * (possibly modified) contents of the key file back to a file; - * otherwise all comments will be lost when the key file is - * written back. + * (possibly modified) contents of the key file back to a file; + * otherwise all comments will be lost when the key file is + * written back. * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the - * (possibly modified) contents of the key file back to a file; - * otherwise only the translations for the current language will be - * written back. + * (possibly modified) contents of the key file back to a file; + * otherwise only the translations for the current language will be + * written back. * * Flags which influence the parsing. */ @@ -257,11 +257,12 @@ /** * G_KEY_FILE_DESKTOP_KEY_TYPE: * - * A key under #G_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. + * A key under %G_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. * * Since: 2.14 */ @@ -269,7 +270,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_VERSION: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the version of the Desktop Entry Specification used for * the desktop entry file. * @@ -279,7 +280,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_NAME: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the specific name of the desktop entry. * * Since: 2.14 @@ -288,7 +289,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the generic name of the desktop entry. * * Since: 2.14 @@ -297,7 +298,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the desktop entry should be shown in menus. * * Since: 2.14 @@ -306,7 +307,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_COMMENT: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the tooltip for the desktop entry. * * Since: 2.14 @@ -315,7 +316,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_ICON: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the name of the icon to be displayed for the desktop * entry. * @@ -325,7 +326,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_HIDDEN: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the desktop entry has been deleted by the user. * * Since: 2.14 @@ -334,7 +335,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 %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of * strings identifying the environments that should display the * desktop entry. * @@ -344,7 +345,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 %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of * strings identifying the environments that should not display the * desktop entry. * @@ -354,7 +355,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * A key under %G_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. @@ -365,7 +366,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_EXEC: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * 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. * @@ -375,7 +376,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_PATH: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * 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. * @@ -385,10 +386,10 @@ /** * G_KEY_FILE_DESKTOP_KEY_TERMINAL: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under %G_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. + * + * It is only valid for desktop entries with the `Application` type. * * Since: 2.14 */ @@ -396,7 +397,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list * of strings giving the MIME types supported by this desktop entry. * * Since: 2.14 @@ -405,7 +406,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_CATEGORIES: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list + * A key under %G_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. * @@ -415,7 +416,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the application supports the * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). * @@ -425,7 +426,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string + * A key under %G_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. @@ -436,7 +437,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_URL: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * 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. * @@ -446,8 +447,8 @@ /** * G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true - * if the application is D-Bus activatable. + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * set to true if the application is D-Bus activatable. * * Since: 2.38 */ @@ -455,7 +456,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_ACTIONS: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list * giving the available application actions. * * Since: 2.38 @@ -464,7 +465,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_APPLICATION: * - * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing applications. * * Since: 2.14 @@ -473,7 +474,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_LINK: * - * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing links to documents. * * Since: 2.14 @@ -482,7 +483,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY: * - * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing directories. * * Since: 2.14 diff --git a/glib/gmain.c b/glib/gmain.c index 6cba3bd53..ba8e0b08c 100644 --- a/glib/gmain.c +++ b/glib/gmain.c @@ -122,7 +122,7 @@ * thread-safe. * * Each event source is assigned a priority. The default priority, - * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. + * %G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. * Values greater than 0 denote lower priorities. Events from high priority * sources are always processed before events from lower priority sources. * @@ -5005,11 +5005,11 @@ g_timeout_source_new_seconds (guint interval) /** * g_timeout_add_full: (rename-to g_timeout_add) * @priority: the priority of the timeout source. Typically this will be in - * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. * @interval: the time between calls to the function, in milliseconds - * (1/1000ths of a second) + * (1/1000ths of a second) * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * @notify: (nullable): function to call when the timeout is removed, or %NULL * * Sets a function to be called at regular intervals, with the given @@ -5069,15 +5069,17 @@ g_timeout_add_full (gint priority, /** * g_timeout_add: * @interval: the time between calls to the function, in milliseconds - * (1/1000ths of a second) + * (1/1000ths of a second) * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * * Sets a function to be called at regular intervals, with the default - * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly - * until it returns %FALSE, at which point the timeout is automatically - * destroyed and the function will not be called again. The first call - * to the function will be at the end of the first @interval. + * priority, %G_PRIORITY_DEFAULT. + * + * The given @function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed and the + * function will not be called again. The first call to the function will be + * at the end of the first @interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. @@ -5118,24 +5120,25 @@ g_timeout_add (guint32 interval, /** * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds) * @priority: the priority of the timeout source. Typically this will be in - * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. * @interval: the time between calls to the function, in seconds * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * @notify: (nullable): function to call when the timeout is removed, or %NULL * * Sets a function to be called at regular intervals, with @priority. - * The function is called repeatedly until it returns %FALSE, at which - * point the timeout is automatically destroyed and the function will - * not be called again. + * + * The function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed and + * the function will not be called again. * * Unlike g_timeout_add(), this function operates at whole second granularity. * The initial starting point of the timer is determined by the implementation * and the implementation is expected to group multiple timers together so that - * they fire all at the same time. - * To allow this grouping, the @interval to the first timer is rounded - * and can deviate up to one second from the specified interval. - * Subsequent timer iterations will generally run at the specified interval. + * they fire all at the same time. To allow this grouping, the @interval to the + * first timer is rounded and can deviate up to one second from the specified + * interval. Subsequent timer iterations will generally run at the specified + * interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. @@ -5198,8 +5201,10 @@ g_timeout_add_seconds_full (gint priority, * @data: data to pass to @function * * Sets a function to be called at regular intervals with the default - * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until - * it returns %FALSE, at which point the timeout is automatically destroyed + * priority, %G_PRIORITY_DEFAULT. + * + * The function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed * and the function will not be called again. * * This internally creates a main loop source using @@ -5753,18 +5758,18 @@ g_child_watch_source_new (GPid pid) /** * g_child_watch_add_full: (rename-to g_child_watch_add) * @priority: the priority of the idle source. Typically this will be in the - * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. - * @pid: process to watch. On POSIX the positive pid of a child process. On + * range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. + * @pid: process to watch. On POSIX the positive pid of a child process. On * Windows a handle for a process (which doesn't have to be a child). * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * @notify: (nullable): function to call when the idle is removed, or %NULL * * Sets a function to be called when the child indicated by @pid * exits, at the priority @priority. * * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() - * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to + * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to * the spawn function for the child watching to work. * * In many programs, you will want to call g_spawn_check_wait_status() @@ -5818,17 +5823,17 @@ g_child_watch_add_full (gint priority, /** * g_child_watch_add: - * @pid: process id to watch. On POSIX the positive pid of a child - * process. On Windows a handle for a process (which doesn't have to be - * a child). + * @pid: process id to watch. On POSIX the positive pid of a child + * process. On Windows a handle for a process (which doesn't have + * to be a child). * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * * Sets a function to be called when the child indicated by @pid - * exits, at a default priority, #G_PRIORITY_DEFAULT. + * exits, at a default priority, %G_PRIORITY_DEFAULT. * * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() - * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to + * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to * the spawn function for the child watching to work. * * Note that on platforms where #GPid must be explicitly closed @@ -5926,13 +5931,15 @@ g_idle_source_new (void) /** * g_idle_add_full: (rename-to g_idle_add) * @priority: the priority of the idle source. Typically this will be in the - * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + * range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * @notify: (nullable): function to call when the idle is removed, or %NULL * * Adds a function to be called whenever there are no higher priority - * events pending. If the function returns %FALSE it is automatically + * events pending. + * + * If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically * removed from the list of event sources and will not be called again. * * See [memory management of sources][mainloop-memory-management] for details @@ -5979,7 +5986,7 @@ g_idle_add_full (gint priority, * * Adds a function to be called whenever there are no higher priority * events pending to the default main loop. The function is given the - * default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function + * default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function * returns %FALSE it is automatically removed from the list of event * sources and will not be called again. * @@ -6035,7 +6042,7 @@ g_idle_remove_by_data (gpointer data) * * In any other case, an idle source is created to call @function and * that source is attached to @context (presumably to be run in another - * thread). The idle source is attached with #G_PRIORITY_DEFAULT + * thread). The idle source is attached with %G_PRIORITY_DEFAULT * priority. If you want a different priority, use * g_main_context_invoke_full(). * diff --git a/glib/gmessages.c b/glib/gmessages.c index e03e6e932..890751297 100644 --- a/glib/gmessages.c +++ b/glib/gmessages.c @@ -383,7 +383,7 @@ myInvalidParameterHandler(const wchar_t *expression, * @...: format string, followed by parameters to insert * into the format string (as with printf()) * - * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). + * Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL). * * Critical warnings are intended to be used in the event of an error * that originated in the current process (a programmer error). @@ -794,40 +794,44 @@ g_log_set_fatal_mask (const gchar *log_domain, /** * g_log_set_handler: * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain + * application domain * @log_levels: the log levels to apply the log handler for. - * To handle fatal and recursive messages as well, combine - * the log levels with the #G_LOG_FLAG_FATAL and - * #G_LOG_FLAG_RECURSION bit flags. + * To handle fatal and recursive messages as well, combine + * the log levels with the %G_LOG_FLAG_FATAL and + * %G_LOG_FLAG_RECURSION bit flags. * @log_func: the log handler function * @user_data: data passed to the log handler * * Sets the log handler for a domain and a set of log levels. + * * To handle fatal and recursive messages the @log_levels parameter - * must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION + * must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION * bit flags. * - * Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if + * Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if * you want to set a handler for this log level you must combine it with - * #G_LOG_FLAG_FATAL. + * %G_LOG_FLAG_FATAL. * * This has no effect if structured logging is enabled; see * [Using Structured Logging][using-structured-logging]. * * Here is an example for adding a log handler for all warning messages * in the default domain: + * * |[ * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * ]| * * This example adds a log handler for all critical messages from GTK+: + * * |[ * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * ]| * * This example adds a log handler for all messages from GLib: + * * |[ * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); @@ -847,11 +851,11 @@ g_log_set_handler (const gchar *log_domain, /** * g_log_set_handler_full: (rename-to g_log_set_handler) * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain + * application domain * @log_levels: the log levels to apply the log handler for. - * To handle fatal and recursive messages as well, combine - * the log levels with the #G_LOG_FLAG_FATAL and - * #G_LOG_FLAG_RECURSION bit flags. + * To handle fatal and recursive messages as well, combine + * the log levels with the %G_LOG_FLAG_FATAL and + * %G_LOG_FLAG_RECURSION bit flags. * @log_func: the log handler function * @user_data: data passed to the log handler * @destroy: destroy notify for @user_data, or %NULL @@ -1419,11 +1423,11 @@ g_logv (const gchar *log_domain, /** * g_log: - * @log_domain: (nullable): the log domain, usually #G_LOG_DOMAIN, or %NULL - * for the default + * @log_domain: (nullable): the log domain, usually %G_LOG_DOMAIN, or %NULL + * for the default * @log_level: the log level, either from #GLogLevelFlags - * or a user-defined level - * @format: the message format. See the printf() documentation + * or a user-defined level + * @format: the message format. See the `printf()` documentation * @...: the parameters to insert into the format string * * Logs an error or debugging message. @@ -1611,10 +1615,12 @@ done_query: * by the key "MESSAGE", followed by a printf()-style message format, * followed by parameters to insert in the format string * - * Log a message with structured data. The message will be passed through to - * the log writer set by the application using g_log_set_writer_func(). If the - * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will - * be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns + * Log a message with structured data. + * + * The message will be passed through to the log writer set by the application + * using g_log_set_writer_func(). If the message is fatal (i.e. its log level + * is %G_LOG_LEVEL_ERROR), the program will be aborted by calling + * G_BREAKPOINT() at the end of this function. If the log writer returns * %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. * See the documentation for #GLogWriterFunc for information on chaining * writers. @@ -1648,9 +1654,10 @@ done_query: * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by * the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including - * glib.h. + * `glib.h`. * * For example: + * * |[ * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", @@ -1671,6 +1678,7 @@ done_query: * interpreted as a string. * * For example: + * * |[ * const GLogField fields[] = { * { "MESSAGE", "This is a debug message.", -1 }, diff --git a/glib/gmessages.h b/glib/gmessages.h index 43c6d67b9..f0b3a8685 100644 --- a/glib/gmessages.h +++ b/glib/gmessages.h @@ -188,7 +188,8 @@ struct _GLogField * chained and fall back to simpler handlers in case of failure. * * Returns: %G_LOG_WRITER_HANDLED if the log entry was handled successfully; - * %G_LOG_WRITER_UNHANDLED otherwise + * %G_LOG_WRITER_UNHANDLED otherwise + * * Since: 2.50 */ typedef GLogWriterOutput (*GLogWriterFunc) (GLogLevelFlags log_level, diff --git a/glib/gshell.c b/glib/gshell.c index afdc04671..33c53497a 100644 --- a/glib/gshell.c +++ b/glib/gshell.c @@ -48,9 +48,11 @@ /** * G_SHELL_ERROR: * - * Error domain for shell functions. Errors in this domain will be from - * the #GShellError enumeration. See #GError for information on error - * domains. + * Error domain for shell functions. + * + * Errors in this domain will be from the #GShellError enumeration. + * + * See #GError for information on error domains. **/ /** @@ -191,13 +193,17 @@ unquote_string_inplace (gchar* str, gchar** end, GError** err) * @unquoted_string: (type filename): a literal string * * Quotes a string so that the shell (/bin/sh) will interpret the - * quoted string to mean @unquoted_string. If you pass a filename to - * the shell, for example, you should first quote it with this - * function. The return value must be freed with g_free(). The - * quoting style used is undefined (single or double quotes may be + * quoted string to mean @unquoted_string. + * + * If you pass a filename to the shell, for example, you should first + * quote it with this function. + * + * The return value must be freed with g_free(). + * + * The quoting style used is undefined (single or double quotes may be * used). * - * Returns: (type filename): quoted string + * Returns: (type filename) (transfer full): quoted string **/ gchar* g_shell_quote (const gchar *unquoted_string) @@ -241,27 +247,33 @@ g_shell_quote (const gchar *unquoted_string) * @quoted_string: (type filename): shell-quoted string * @error: error return location or NULL * - * Unquotes a string as the shell (/bin/sh) would. Only handles - * quotes; if a string contains file globs, arithmetic operators, - * variables, backticks, redirections, or other special-to-the-shell - * features, the result will be different from the result a real shell - * would produce (the variables, backticks, etc. will be passed - * through literally instead of being expanded). This function is - * guaranteed to succeed if applied to the result of + * Unquotes a string as the shell (/bin/sh) would. + * + * This function only handles quotes; if a string contains file globs, + * arithmetic operators, variables, backticks, redirections, or other + * special-to-the-shell features, the result will be different from the + * result a real shell would produce (the variables, backticks, etc. + * will be passed through literally instead of being expanded). + * + * This function is guaranteed to succeed if applied to the result of * g_shell_quote(). If it fails, it returns %NULL and sets the - * error. The @quoted_string need not actually contain quoted or - * escaped text; g_shell_unquote() simply goes through the string and - * unquotes/unescapes anything that the shell would. Both single and - * double quotes are handled, as are escapes including escaped - * newlines. The return value must be freed with g_free(). Possible - * errors are in the #G_SHELL_ERROR domain. + * error. + * + * The @quoted_string need not actually contain quoted or escaped text; + * g_shell_unquote() simply goes through the string and unquotes/unescapes + * anything that the shell would. Both single and double quotes are + * handled, as are escapes including escaped newlines. + * + * The return value must be freed with g_free(). + * + * Possible errors are in the %G_SHELL_ERROR domain. * * Shell quoting rules are a bit strange. Single quotes preserve the * literal string exactly. escape sequences are not allowed; not even - * \' - if you want a ' in the quoted text, you have to do something - * like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to - * be escaped with backslash. Otherwise double quotes preserve things - * literally. + * `\'` - if you want a `'` in the quoted text, you have to do something + * like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and + * newline to be escaped with backslash. Otherwise double quotes + * preserve things literally. * * Returns: (type filename): an unquoted string **/ @@ -625,12 +637,16 @@ tokenize_command_line (const gchar *command_line, * Parses a command line into an argument vector, in much the same way * the shell would, but without many of the expansions the shell would * perform (variable expansion, globs, operators, filename expansion, - * etc. are not supported). The results are defined to be the same as - * those you would get from a UNIX98 /bin/sh, as long as the input - * contains none of the unsupported shell expansions. If the input - * does contain such expansions, they are passed through - * literally. Possible errors are those from the #G_SHELL_ERROR - * domain. Free the returned vector with g_strfreev(). + * etc. are not supported). + * + * The results are defined to be the same as those you would get from + * a UNIX98 `/bin/sh`, as long as the input contains none of the + * unsupported shell expansions. If the input does contain such expansions, + * they are passed through literally. + * + * Possible errors are those from the %G_SHELL_ERROR domain. + * + * Free the returned vector with g_strfreev(). * * Returns: %TRUE on success, %FALSE if error set **/ diff --git a/glib/gslice.c b/glib/gslice.c index d6335c9dd..690d21e07 100644 --- a/glib/gslice.c +++ b/glib/gslice.c @@ -998,6 +998,7 @@ thread_memory_magazine2_free (ThreadMemory *tmem, * @next: the field name of the next pointer in @type * * Frees a linked list of memory blocks of structure type @type. + * * The memory blocks must be equal-sized, allocated via * g_slice_alloc() or g_slice_alloc0() and linked together by * a @next pointer (similar to #GSList). The name of the @@ -1016,17 +1017,19 @@ thread_memory_magazine2_free (ThreadMemory *tmem, * @block_size: the number of bytes to allocate * * Allocates a block of memory from the slice allocator. + * * The block address handed out can be expected to be aligned - * to at least 1 * sizeof (void*), - * though in general slices are 2 * sizeof (void*) bytes aligned, - * if a malloc() fallback implementation is used instead, - * the alignment may be reduced in a libc dependent fashion. + * to at least `1 * sizeof (void*)`, though in general slices + * are `2 * sizeof (void*)` bytes aligned; if a `malloc()` + * fallback implementation is used instead, the alignment may + * be reduced in a libc dependent fashion. + * * Note that the underlying slice allocation mechanism can * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * - * Returns: a pointer to the allocated memory block, which will be %NULL if and - * only if @mem_size is 0 + * Returns: a pointer to the allocated memory block, which will + * be %NULL if and only if @mem_size is 0 * * Since: 2.10 */ diff --git a/glib/gspawn.c b/glib/gspawn.c index 51e6eb01d..51b4c79ac 100644 --- a/glib/gspawn.c +++ b/glib/gspawn.c @@ -209,6 +209,8 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error) * @user_data: (closure): user data for @child_setup * @child_pid: (out) (optional): return location for child process reference, or %NULL * @error: return location for error + * + * Executes a child program asynchronously. * * See g_spawn_async_with_pipes() for a full description; this function * simply calls the g_spawn_async_with_pipes() without any pipes. @@ -216,7 +218,7 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error) * You should call g_spawn_close_pid() on the returned child process * reference when you don't need it any more. * - * If you are writing a GTK+ application, and the program you are spawning is a + * If you are writing a GTK application, and the program you are spawning is a * graphical application too, then to ensure that the spawned program opens its * windows on the right screen, you may want to use #GdkAppLaunchContext, * #GAppLaunchContext, or set the %DISPLAY environment variable. @@ -329,6 +331,7 @@ read_data (GString *str, * @error: return location for error, or %NULL * * Executes a child synchronously (waits for the child to exit before returning). + * * All output from the child is stored in @standard_output and @standard_error, * if those parameters are non-%NULL. Note that you must set the * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when @@ -665,52 +668,53 @@ g_spawn_async_with_pipes (const gchar *working_directory, * @error: return location for error * * Executes a child program asynchronously (your program will not - * block waiting for the child to exit). The child program is - * specified by the only argument that must be provided, @argv. - * @argv should be a %NULL-terminated array of strings, to be passed - * as the argument vector for the child. The first string in @argv - * is of course the name of the program to execute. By default, the - * name of the program must be a full path. If @flags contains the - * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is - * used to search for the executable. If @flags contains the - * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from - * @envp is used to search for the executable. If both the - * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags - * are set, the `PATH` variable from @envp takes precedence over - * the environment variable. + * block waiting for the child to exit). * - * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not - * used, then the program will be run from the current directory (or - * @working_directory, if specified); this might be unexpected or even + * The child program is specified by the only argument that must be + * provided, @argv. @argv should be a %NULL-terminated array of strings, + * to be passed as the argument vector for the child. The first string + * in @argv is of course the name of the program to execute. By default, + * the name of the program must be a full path. If @flags contains the + * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to + * search for the executable. If @flags contains the + * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp + * is used to search for the executable. If both the + * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are + * set, the `PATH` variable from @envp takes precedence over the + * environment variable. + * + * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag + * is not used, then the program will be run from the current directory + * (or @working_directory, if specified); this might be unexpected or even * dangerous in some cases when the current directory is world-writable. * * On Windows, note that all the string or string vector arguments to - * this function and the other g_spawn*() functions are in UTF-8, the + * this function and the other `g_spawn*()` functions are in UTF-8, the * GLib file name encoding. Unicode characters that are not part of * the system codepage passed in these arguments will be correctly * available in the spawned program only if it uses wide character API * to retrieve its command line. For C programs built with Microsoft's - * tools it is enough to make the program have a wmain() instead of - * main(). wmain() has a wide character argument vector as parameter. + * tools it is enough to make the program have a `wmain()` instead of + * `main()`. `wmain()` has a wide character argument vector as parameter. * - * At least currently, mingw doesn't support wmain(), so if you use + * At least currently, mingw doesn't support `wmain()`, so if you use * mingw to develop the spawned program, it should call * g_win32_get_command_line() to get arguments in UTF-8. * - * On Windows the low-level child process creation API CreateProcess() + * On Windows the low-level child process creation API `CreateProcess()` * doesn't use argument vectors, but a command line. The C runtime - * library's spawn*() family of functions (which g_spawn_async_with_pipes() + * library's `spawn*()` family of functions (which g_spawn_async_with_pipes() * eventually calls) paste the argument vector elements together into * a command line, and the C runtime startup code does a corresponding * reconstruction of an argument vector from the command line, to be - * passed to main(). Complications arise when you have argument vector + * passed to `main()`. Complications arise when you have argument vector * elements that contain spaces or double quotes. The `spawn*()` functions * don't do any quoting or escaping, but on the other hand the startup * code does do unquoting and unescaping in order to enable receiving * arguments with embedded spaces or double quotes. To work around this * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on * argument vector elements that need it before calling the C runtime - * spawn() function. + * `spawn()` function. * * The returned @child_pid on Windows is a handle to the child * process, not its identifier. Process handles and process @@ -729,13 +733,13 @@ g_spawn_async_with_pipes (const gchar *working_directory, * free resources which may be associated with the child process. (On Unix, * using a child watch is equivalent to calling waitpid() or handling * the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid() - * is equivalent to calling CloseHandle() on the process handle returned + * is equivalent to calling `CloseHandle()` on the process handle returned * in @child_pid). See g_child_watch_add(). * * Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically * closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that * other open file descriptors will be inherited by the child; otherwise all - * descriptors except stdin/stdout/stderr will be closed before calling exec() + * descriptors except stdin/stdout/stderr will be closed before calling `exec()` * in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an * absolute path, it will be looked for in the `PATH` environment * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an @@ -776,25 +780,25 @@ g_spawn_async_with_pipes (const gchar *working_directory, * @child_setup and @user_data are a function and user data. On POSIX * platforms, the function is called in the child after GLib has * performed all the setup it plans to perform (including creating - * pipes, closing file descriptors, etc.) but before calling exec(). - * That is, @child_setup is called just before calling exec() in the + * pipes, closing file descriptors, etc.) but before calling `exec()`. + * That is, @child_setup is called just before calling `exec()` in the * child. Obviously actions taken in this function will only affect * the child, not the parent. * - * On Windows, there is no separate fork() and exec() functionality. + * On Windows, there is no separate `fork()` and `exec()` functionality. * Child processes are created and run with a single API call, - * CreateProcess(). There is no sensible thing @child_setup + * `CreateProcess()`. There is no sensible thing @child_setup * could be used for on Windows so it is ignored and not called. * * If non-%NULL, @child_pid will on Unix be filled with the child's * process ID. You can use the process ID to send signals to the child, - * or to use g_child_watch_add() (or waitpid()) if you specified the + * or to use g_child_watch_add() (or `waitpid()`) if you specified the * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be * filled with a handle to the child process only if you specified the * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child * process using the Win32 API, for example wait for its termination - * with the WaitFor*() functions, or examine its exit code with - * GetExitCodeProcess(). You should close the handle with CloseHandle() + * with the `WaitFor*()` functions, or examine its exit code with + * `GetExitCodeProcess()`. You should close the handle with `CloseHandle()` * or g_spawn_close_pid() when you no longer need it. * * If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out @@ -818,7 +822,7 @@ g_spawn_async_with_pipes (const gchar *working_directory, * @error can be %NULL to ignore errors, or non-%NULL to report errors. * If an error is set, the function returns %FALSE. Errors are reported * even if they occur in the child (for example if the executable in - * @argv[0] is not found). Typically the `message` field of returned + * `@argv[0]` is not found). Typically the `message` field of returned * errors should be displayed to users. Possible errors are those from * the #G_SPAWN_ERROR domain. * @@ -829,7 +833,7 @@ g_spawn_async_with_pipes (const gchar *working_directory, * process reference must be closed using g_spawn_close_pid(). * * On modern UNIX platforms, GLib can use an efficient process launching - * codepath driven internally by posix_spawn(). This has the advantage of + * codepath driven internally by `posix_spawn()`. This has the advantage of * avoiding the fork-time performance costs of cloning the parent process * address space, and avoiding associated memory overcommit checks that are * not relevant in the context of immediately executing a distinct process. @@ -841,9 +845,11 @@ g_spawn_async_with_pipes (const gchar *working_directory, * 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set * 4. @working_directory is %NULL * 5. @child_setup is %NULL - * 6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath. + * 6. The program is of a recognised binary format, or has a shebang. + * Otherwise, GLib will have to execute the program through the + * shell, which is not done using the optimized codepath. * - * If you are writing a GTK+ application, and the program you are spawning is a + * If you are writing a GTK application, and the program you are spawning is a * graphical application too, then to ensure that the spawned program opens its * windows on the right screen, you may want to use #GdkAppLaunchContext, * #GAppLaunchContext, or set the `DISPLAY` environment variable. @@ -925,6 +931,8 @@ g_spawn_async_with_pipes_and_fds (const gchar *working_directory, * @stderr_fd: file descriptor to use for child's stderr, or `-1` * @error: return location for error * + * Executes a child program asynchronously. + * * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, * so no FD assignments are used. * @@ -986,12 +994,17 @@ g_spawn_async_with_fds (const gchar *working_directory, * @error: return location for errors * * A simple version of g_spawn_sync() with little-used parameters - * removed, taking a command line instead of an argument vector. See - * g_spawn_sync() for full details. @command_line will be parsed by - * g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag - * is enabled. Note that %G_SPAWN_SEARCH_PATH can have security - * implications, so consider using g_spawn_sync() directly if - * appropriate. Possible errors are those from g_spawn_sync() and those + * removed, taking a command line instead of an argument vector. + * + * See g_spawn_sync() for full details. + * + * The @command_line argument will be parsed by g_shell_parse_argv(). + * + * Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled. + * Note that %G_SPAWN_SEARCH_PATH can have security implications, so + * consider using g_spawn_sync() directly if appropriate. + * + * Possible errors are those from g_spawn_sync() and those * from g_shell_parse_argv(). * * If @wait_status is non-%NULL, the platform-specific status of @@ -1050,8 +1063,9 @@ g_spawn_command_line_sync (const gchar *command_line, * @error: return location for errors * * A simple version of g_spawn_async() that parses a command line with - * g_shell_parse_argv() and passes it to g_spawn_async(). Runs a - * command line in the background. Unlike g_spawn_async(), the + * g_shell_parse_argv() and passes it to g_spawn_async(). + * + * Runs a command line in the background. Unlike g_spawn_async(), the * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note * that %G_SPAWN_SEARCH_PATH can have security implications, so * consider using g_spawn_async() directly if appropriate. Possible @@ -1134,7 +1148,7 @@ g_spawn_command_line_async (const gchar *command_line, * functionality, although under a misleading name. * * Returns: %TRUE if child exited successfully, %FALSE otherwise (and - * @error will be set) + * @error will be set) * * Since: 2.70 */ diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index b6ff60f51..ef6920643 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -2028,22 +2028,26 @@ g_strncasecmp (const gchar *s1, * @new_delimiter: the new delimiter character * * Converts any delimiter characters in @string to @new_delimiter. + * * Any characters in @string which are found in @delimiters are * changed to the @new_delimiter character. Modifies @string in place, - * and returns @string itself, not a copy. The return value is to - * allow nesting such as + * and returns @string itself, not a copy. + * + * The return value is to allow nesting such as: + * * |[ * g_ascii_strup (g_strdelimit (str, "abc", '?')) * ]| * - * In order to modify a copy, you may use `g_strdup()`: + * In order to modify a copy, you may use g_strdup(): + * * |[ * reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); * ... * g_free (reformatted); * ]| * - * Returns: @string + * Returns: the modified @string */ gchar * g_strdelimit (gchar *string, @@ -2073,21 +2077,24 @@ g_strdelimit (gchar *string, * @substitutor: replacement character for disallowed bytes * * For each character in @string, if the character is not in @valid_chars, - * replaces the character with @substitutor. Modifies @string in place, - * and return @string itself, not a copy. The return value is to allow - * nesting such as + * replaces the character with @substitutor. + * + * Modifies @string in place, and return @string itself, not a copy. The + * return value is to allow nesting such as: + * * |[ * g_ascii_strup (g_strcanon (str, "abc", '?')) * ]| * - * In order to modify a copy, you may use `g_strdup()`: + * In order to modify a copy, you may use g_strdup(): + * * |[ * reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); * ... * g_free (reformatted); * ]| * - * Returns: @string + * Returns: the modified @string */ gchar * g_strcanon (gchar *string, diff --git a/glib/gthread.c b/glib/gthread.c index 29216d7fd..08389468c 100644 --- a/glib/gthread.c +++ b/glib/gthread.c @@ -164,16 +164,17 @@ * G_LOCK_DEFINE: * @name: the name of the lock * - * The #G_LOCK_ macros provide a convenient interface to #GMutex. - * #G_LOCK_DEFINE defines a lock. It can appear in any place where + * The `G_LOCK_` macros provide a convenient interface to #GMutex. + * %G_LOCK_DEFINE defines a lock. It can appear in any place where * variable definitions may appear in programs, i.e. in the first block * of a function or outside of functions. The @name parameter will be * mangled to get the name of the #GMutex. This means that you * can use names of existing variables as the parameter - e.g. the name * of the variable you intend to protect with the lock. Look at our - * give_me_next_number() example using the #G_LOCK macros: + * give_me_next_number() example using the `G_LOCK` macros: + * + * Here is an example for using the `G_LOCK` convenience macros: * - * Here is an example for using the #G_LOCK convenience macros: * |[ * G_LOCK_DEFINE (current_number); * @@ -196,14 +197,14 @@ * G_LOCK_DEFINE_STATIC: * @name: the name of the lock * - * This works like #G_LOCK_DEFINE, but it creates a static object. + * This works like %G_LOCK_DEFINE, but it creates a static object. */ /** * G_LOCK_EXTERN: * @name: the name of the lock * - * This declares a lock, that is defined with #G_LOCK_DEFINE in another + * This declares a lock, that is defined with %G_LOCK_DEFINE in another * module. */ @@ -212,7 +213,7 @@ * @name: the name of the lock * * Works like g_mutex_lock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. */ /** @@ -220,7 +221,7 @@ * @name: the name of the lock * * Works like g_mutex_trylock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. * * Returns: %TRUE, if the lock could be locked. */ @@ -230,7 +231,7 @@ * @name: the name of the lock * * Works like g_mutex_unlock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. */ /* GMutex Documentation {{{1 ------------------------------------------ */ diff --git a/glib/gunicode.h b/glib/gunicode.h index e6985d220..f2ad3ca86 100644 --- a/glib/gunicode.h +++ b/glib/gunicode.h @@ -760,10 +760,15 @@ GLIB_VAR const gchar * const g_utf8_skip; * g_utf8_next_char: * @p: Pointer to the start of a valid UTF-8 character * - * Skips to the next character in a UTF-8 string. The string must be - * valid; this macro is as fast as possible, and has no error-checking. - * You would use this macro to iterate over a string character by - * character. The macro returns the start of the next UTF-8 character. + * Skips to the next character in a UTF-8 string. + * + * The string must be valid; this macro is as fast as possible, and has + * no error-checking. + * + * You would use this macro to iterate over a string character by character. + * + * The macro returns the start of the next UTF-8 character. + * * Before using this macro, use g_utf8_validate() to validate strings * that may contain invalid UTF-8. */ diff --git a/glib/gvariant.h b/glib/gvariant.h index c0587a887..11c74d596 100644 --- a/glib/gvariant.h +++ b/glib/gvariant.h @@ -345,7 +345,9 @@ GQuark g_variant_parse_error_quark (void); * A stack-allocated #GVariantBuilder must be initialized if it is * used together with g_auto() to avoid warnings or crashes if * function returns before g_variant_builder_init() is called on the - * builder. This macro can be used as initializer instead of an + * builder. + * + * This macro can be used as initializer instead of an * explicit zeroing a variable when declaring it and a following * g_variant_builder_init(), but it cannot be assigned to a variable. * @@ -354,7 +356,7 @@ GQuark g_variant_parse_error_quark (void); * the G_VARIANT_BUILDER_INIT() call, but rather in functions that * make sure that #GVariantBuilder is valid. * - * |[ + * |[ * g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING); * ]| * @@ -455,6 +457,7 @@ struct _GVariantDict { * A stack-allocated #GVariantDict must be initialized if it is used * together with g_auto() to avoid warnings or crashes if function * returns before g_variant_dict_init() is called on the builder. + * * This macro can be used as initializer instead of an explicit * zeroing a variable when declaring it and a following * g_variant_dict_init(), but it cannot be assigned to a variable. @@ -468,7 +471,7 @@ struct _GVariantDict { * safely with a different @asv right after the variable was * initialized with G_VARIANT_DICT_INIT(). * - * |[ + * |[ * g_autoptr(GVariant) variant = get_asv_variant (); * g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant); * ]| diff --git a/glib/gversion.c b/glib/gversion.c index 02acb7d8e..9b7765c8e 100644 --- a/glib/gversion.c +++ b/glib/gversion.c @@ -151,24 +151,25 @@ const guint glib_binary_age = GLIB_BINARY_AGE; * @required_micro: the required micro version * * Checks that the GLib library in use is compatible with the - * given version. Generally you would pass in the constants - * #GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION - * as the three arguments to this function; that produces - * a check that the library in use is compatible with - * the version of GLib the application or module was compiled - * against. + * given version. + * + * Generally you would pass in the constants %GLIB_MAJOR_VERSION, + * %GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments + * to this function; that produces a check that the library in use + * is compatible with the version of GLib the application or module + * was compiled against. * * Compatibility is defined by two things: first the version * of the running library is newer than the version - * @required_major.required_minor.@required_micro. Second + * `@required_major.required_minor.@required_micro`. Second * the running library must be binary compatible with the - * version @required_major.required_minor.@required_micro + * version `@required_major.@required_minor.@required_micro` * (same major version.) * - * Returns: %NULL if the GLib library is compatible with the - * given version, or a string describing the version mismatch. - * The returned string is owned by GLib and must not be modified - * or freed. + * Returns: (transfer none) (nullable): %NULL if the GLib library is + * compatible with the given version, or a string describing the + * version mismatch. The returned string is owned by GLib and must + * not be modified or freed. * * Since: 2.6 */ diff --git a/gobject/gbinding.c b/gobject/gbinding.c index 48b4fbaec..a0b5de102 100644 --- a/gobject/gbinding.c +++ b/gobject/gbinding.c @@ -25,11 +25,12 @@ * * #GBinding is the representation of a binding between a property on a * #GObject instance (or source) and another property on another #GObject - * instance (or target). Whenever the source property changes, the same - * value is applied to the target property; for instance, the following - * binding: + * instance (or target). * - * |[ + * Whenever the source property changes, the same value is applied to the + * target property; for instance, the following binding: + * + * |[ * g_object_bind_property (object1, "property-a", * object2, "property-b", * G_BINDING_DEFAULT); @@ -1409,10 +1410,12 @@ g_object_bind_property_full (gpointer source, * @flags: flags to pass to #GBinding * * Creates a binding between @source_property on @source and @target_property - * on @target. Whenever the @source_property is changed the @target_property is + * on @target. + * + * Whenever the @source_property is changed the @target_property is * updated using the same value. For instance: * - * |[ + * |[ * g_object_bind_property (action, "active", widget, "sensitive", 0); * ]| * diff --git a/gobject/gbinding.h b/gobject/gbinding.h index 84dad7f86..2b2521423 100644 --- a/gobject/gbinding.h +++ b/gobject/gbinding.h @@ -53,8 +53,9 @@ typedef struct _GBinding GBinding; * @to_value: the #GValue in which to store the transformed value * @user_data: data passed to the transform function * - * A function to be called to transform @from_value to @to_value. If - * this is the @transform_to function of a binding, then @from_value + * A function to be called to transform @from_value to @to_value. + * + * If this is the @transform_to function of a binding, then @from_value * is the @source_property on the @source object, and @to_value is the * @target_property on the @target object. If this is the * @transform_from function of a %G_BINDING_BIDIRECTIONAL binding, diff --git a/gobject/gboxed.c b/gobject/gboxed.c index e6bd786ab..c1624a598 100644 --- a/gobject/gboxed.c +++ b/gobject/gboxed.c @@ -39,10 +39,11 @@ * @see_also: #GParamSpecBoxed, g_param_spec_boxed() * @title: Boxed Types * - * #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only - * thing the type system needs to know about the structures is how to copy them - * (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that - * they are treated as opaque chunks of memory. + * #GBoxed is a generic wrapper mechanism for arbitrary C structures. + * + * The only thing the type system needs to know about the structures is how to + * copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc); + * beyond that, they are treated as opaque chunks of memory. * * Boxed types are useful for simple value-holder structures like rectangles or * points. They can also be used for wrapping structures defined in non-#GObject @@ -280,8 +281,10 @@ boxed_proxy_lcopy_value (const GValue *value, * @boxed_free: Boxed structure free function. * * This function creates a new %G_TYPE_BOXED derived type id for a new - * boxed type with name @name. Boxed type handling functions have to be - * provided to copy and free opaque boxed structures of this type. + * boxed type with name @name. + * + * Boxed type handling functions have to be provided to copy and free + * opaque boxed structures of this type. * * For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE * instead of calling g_boxed_type_register_static() directly. The macro @@ -510,6 +513,7 @@ g_value_set_boxed (GValue *value, * @v_boxed: (nullable): static boxed value to be set * * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + * * The boxed value is assumed to be static, and is thus not duplicated * when setting the #GValue. */ diff --git a/gobject/gclosure.c b/gobject/gclosure.c index 364f4aab1..e6720524a 100644 --- a/gobject/gclosure.c +++ b/gobject/gclosure.c @@ -41,8 +41,9 @@ * @short_description: Functions as first-class objects * @title: Closures * - * A #GClosure represents a callback supplied by the programmer. It - * will generally comprise a function of some kind and a marshaller + * A #GClosure represents a callback supplied by the programmer. + * + * It will generally comprise a function of some kind and a marshaller * used to call it. It is the responsibility of the marshaller to * convert the arguments for the invocation from #GValues into * a suitable form, perform the callback on the converted arguments, @@ -150,8 +151,9 @@ enum { * @data: data to store in the @data field of the newly allocated #GClosure * * Allocates a struct of the given size and initializes the initial - * part as a #GClosure. This function is mainly useful when - * implementing new types of closures. + * part as a #GClosure. + * + * This function is mainly useful when implementing new types of closures: * * |[ * typedef struct _MyClosure MyClosure; @@ -327,12 +329,15 @@ g_closure_set_meta_va_marshal (GClosure *closure, * to @meta_marshal * @meta_marshal: a #GClosureMarshal function * - * Sets the meta marshaller of @closure. A meta marshaller wraps - * @closure->marshal and modifies the way it is called in some - * fashion. The most common use of this facility is for C callbacks. + * Sets the meta marshaller of @closure. + * + * A meta marshaller wraps the @closure's marshal and modifies the way + * it is called in some fashion. The most common use of this facility + * is for C callbacks. + * * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), * are used everywhere, but the way that we get the callback function - * differs. In most cases we want to use @closure->callback, but in + * differs. In most cases we want to use the @closure's callback, but in * other cases we want to use some different technique to retrieve the * callback function. * @@ -373,9 +378,11 @@ g_closure_set_meta_marshal (GClosure *closure, * @post_marshal_notify: a function to call after the closure callback * * Adds a pair of notifiers which get invoked before and after the - * closure callback, respectively. This is typically used to protect - * the extra arguments for the duration of the callback. See - * g_object_watch_closure() for an example of marshal guards. + * closure callback, respectively. + * + * This is typically used to protect the extra arguments for the + * duration of the callback. See g_object_watch_closure() for an + * example of marshal guards. */ void g_closure_add_marshal_guards (GClosure *closure, @@ -428,11 +435,12 @@ g_closure_add_marshal_guards (GClosure *closure, * @notify_func: the callback function to register * * Registers a finalization notifier which will be called when the - * reference count of @closure goes down to 0. Multiple finalization - * notifiers on a single closure are invoked in unspecified order. If - * a single call to g_closure_unref() results in the closure being - * both invalidated and finalized, then the invalidate notifiers will - * be run before the finalize notifiers. + * reference count of @closure goes down to 0. + * + * Multiple finalization notifiers on a single closure are invoked in + * unspecified order. If a single call to g_closure_unref() results in + * the closure being both invalidated and finalized, then the invalidate + * notifiers will be run before the finalize notifiers. */ void g_closure_add_finalize_notifier (GClosure *closure, @@ -464,9 +472,10 @@ g_closure_add_finalize_notifier (GClosure *closure, * @notify_func: the callback function to register * * Registers an invalidation notifier which will be called when the - * @closure is invalidated with g_closure_invalidate(). Invalidation - * notifiers are invoked before finalization notifiers, in an - * unspecified order. + * @closure is invalidated with g_closure_invalidate(). + * + * Invalidation notifiers are invoked before finalization notifiers, + * in an unspecified order. */ void g_closure_add_invalidate_notifier (GClosure *closure, @@ -561,7 +570,9 @@ g_closure_ref (GClosure *closure) * Sets a flag on the closure to indicate that its calling * environment has become invalid, and thus causes any future * invocations of g_closure_invoke() on this @closure to be - * ignored. Also, invalidation notifiers installed on the closure will + * ignored. + * + * Also, invalidation notifiers installed on the closure will * be called at this point. Note that unless you are holding a * reference to the closure yourself, the invalidation notifiers may * unref the closure and cause it to be destroyed, so if you need to @@ -594,8 +605,10 @@ g_closure_invalidate (GClosure *closure) * @closure: #GClosure to decrement the reference count on * * Decrements the reference count of a closure after it was previously - * incremented by the same caller. If no other callers are using the - * closure, then the closure will be destroyed and freed. + * incremented by the same caller. + * + * If no other callers are using the closure, then the closure will be + * destroyed and freed. */ void g_closure_unref (GClosure *closure) @@ -640,27 +653,34 @@ g_closure_unref (GClosure *closure) * @closure: #GClosure to decrement the initial reference count on, if it's * still being held * - * Takes over the initial ownership of a closure. Each closure is - * initially created in a "floating" state, which means that the initial - * reference count is not owned by any caller. g_closure_sink() checks - * to see if the object is still floating, and if so, unsets the - * floating state and decreases the reference count. If the closure - * is not floating, g_closure_sink() does nothing. The reason for the - * existence of the floating state is to prevent cumbersome code - * sequences like: + * Takes over the initial ownership of a closure. + * + * Each closure is initially created in a "floating" state, which means + * that the initial reference count is not owned by any caller. + * + * This function checks to see if the object is still floating, and if so, + * unsets the floating state and decreases the reference count. If the + * closure is not floating, g_closure_sink() does nothing. + * + * The reason for the existence of the floating state is to prevent + * cumbersome code sequences like: + * * |[ * closure = g_cclosure_new (cb_func, cb_data); * g_source_set_closure (source, closure); * g_closure_unref (closure); // GObject doesn't really need this * ]| + * * Because g_source_set_closure() (and similar functions) take ownership of the * initial reference count, if it is unowned, we instead can write: + * * |[ * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); * ]| * * Generally, this function is used together with g_closure_ref(). An example * of storing a closure for later notification looks like: + * * |[ * static GClosure *notify_closure = NULL; * void @@ -888,12 +908,16 @@ _g_closure_invoke_va (GClosure *closure, * @closure: a #GClosure * @marshal: a #GClosureMarshal function * - * Sets the marshaller of @closure. The `marshal_data` - * of @marshal provides a way for a meta marshaller to provide additional - * information to the marshaller. (See g_closure_set_meta_marshal().) For - * GObject's C predefined marshallers (the g_cclosure_marshal_*() + * Sets the marshaller of @closure. + * + * The `marshal_data` of @marshal provides a way for a meta marshaller to + * provide additional information to the marshaller. + * + * For GObject's C predefined marshallers (the `g_cclosure_marshal_*()` * functions), what it provides is a callback function to use instead of * @closure->callback. + * + * See also: g_closure_set_meta_marshal() */ void g_closure_set_marshal (GClosure *closure, diff --git a/gobject/gclosure.h b/gobject/gclosure.h index 884e403a8..f30499e86 100644 --- a/gobject/gclosure.h +++ b/gobject/gclosure.h @@ -42,6 +42,7 @@ G_BEGIN_DECLS * @cl: a #GClosure * * Get the total number of notifiers connected with the closure @cl. + * * The count includes the meta marshaller, the finalize and invalidate notifiers * and the marshal guards. Note that each guard counts as two notifiers. * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), @@ -78,10 +79,13 @@ typedef struct _GClosureNotifyData GClosureNotifyData; * GCallback: * * The type used for callback functions in structure definitions and function - * signatures. This doesn't mean that all callback functions must take no - * parameters and return void. The required signature of a callback function - * is determined by the context in which is used (e.g. the signal to which it - * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. + * signatures. + * + * This doesn't mean that all callback functions must take no parameters and + * return void. The required signature of a callback function is determined by + * the context in which is used (e.g. the signal to which it is connected). + * + * Use G_CALLBACK() to cast the callback function to a #GCallback. */ typedef void (*GCallback) (void); /** diff --git a/gobject/gobject.c b/gobject/gobject.c index a88682360..9776d7c95 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -66,15 +66,18 @@ * claimed to be "owned" by any code portion. The main motivation for * providing floating references is C convenience. In particular, it * allows code to be written as: + * * |[ * container = create_container (); * container_add_child (container, create_child()); * ]| + * * If container_add_child() calls g_object_ref_sink() on the passed-in child, * no reference of the newly created child is leaked. Without floating * references, container_add_child() can only g_object_ref() the new child, * so to implement this code without reference leaks, it would have to be * written as: + * * |[ * Child *child; * container = create_container (); @@ -82,6 +85,7 @@ * container_add_child (container, child); * g_object_unref (child); * ]| + * * The floating reference can be converted into an ordinary reference by * calling g_object_ref_sink(). For already sunken objects (objects that * don't have a floating reference anymore), g_object_ref_sink() is equivalent @@ -537,11 +541,13 @@ g_object_do_class_init (GObjectClass *class) * This signal is typically used to obtain change notification for a * single property, by specifying the property name as a detail in the * g_signal_connect() call, like this: + * * |[ * g_signal_connect (text_view->buffer, "notify::paste-target-list", * G_CALLBACK (gtk_text_view_target_list_notify), * text_view) * ]| + * * It is important to note that you must use * [canonical parameter names][canonical-parameter-names] as * detail strings for the notify signal. @@ -4530,11 +4536,12 @@ g_initially_unowned_class_init (GInitiallyUnownedClass *klass) /** * GWeakRef: * - * A structure containing a weak reference to a #GObject. It can either - * be empty (i.e. point to %NULL), or point to an object for as long as - * at least one "strong" reference to that object exists. Before the - * object's #GObjectClass.dispose method is called, every #GWeakRef - * associated with becomes empty (i.e. points to %NULL). + * A structure containing a weak reference to a #GObject. + * + * A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an + * object for as long as at least one "strong" reference to that object + * exists. Before the object's #GObjectClass.dispose method is called, + * every #GWeakRef associated with becomes empty (i.e. points to %NULL). * * Like #GValue, #GWeakRef can be statically allocated, stack- or * heap-allocated, or embedded in larger structures. diff --git a/gobject/gobject.h b/gobject/gobject.h index 86e2b7de1..f62f9c902 100644 --- a/gobject/gobject.h +++ b/gobject/gobject.h @@ -45,6 +45,7 @@ G_BEGIN_DECLS * @object: Object which is subject to casting. * * Casts a #GObject or derived pointer into a (GObject*) pointer. + * * Depending on the current debugging level, this function may invoke * certain runtime checks to identify invalid casts. */ @@ -144,7 +145,9 @@ G_BEGIN_DECLS * @object: Object which is subject to casting. * * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) - * pointer. Depending on the current debugging level, this function may invoke + * pointer. + * + * Depending on the current debugging level, this function may invoke * certain runtime checks to identify invalid casts. */ #define G_INITIALLY_UNOWNED(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnowned)) @@ -230,17 +233,21 @@ typedef void (*GObjectFinalizeFunc) (GObject *object); * @where_the_object_was: the object being disposed * * A #GWeakNotify function can be added to an object as a callback that gets - * triggered when the object is finalized. Since the object is already being - * disposed when the #GWeakNotify is called, there's not much you could do - * with the object, apart from e.g. using its address as hash-index or the like. + * triggered when the object is finalized. + * + * Since the object is already being disposed when the #GWeakNotify is called, + * there's not much you could do with the object, apart from e.g. using its + * address as hash-index or the like. */ typedef void (*GWeakNotify) (gpointer data, GObject *where_the_object_was); /** * GObject: + * + * The base object type. * - * All the fields in the GObject structure are private - * to the #GObject implementation and should never be accessed directly. + * All the fields in the `GObject` structure are private to the implementation + * and should never be accessed directly. */ struct _GObject { @@ -352,14 +359,14 @@ struct _GObjectClass /* padding */ gpointer pdummy[6]; }; + /** * GObjectConstructParam: * @pspec: the #GParamSpec of the construct parameter * @value: the value to set the parameter to * - * The GObjectConstructParam struct is an auxiliary - * structure used to hand #GParamSpec/#GValue pairs to the @constructor of - * a #GObjectClass. + * The GObjectConstructParam struct is an auxiliary structure used to hand + * #GParamSpec/#GValue pairs to the @constructor of a #GObjectClass. */ struct _GObjectConstructParam { @@ -369,10 +376,11 @@ struct _GObjectConstructParam /** * GInitiallyUnowned: + * + * A type for objects that have an initially floating reference. * - * All the fields in the GInitiallyUnowned structure - * are private to the #GInitiallyUnowned implementation and should never be - * accessed directly. + * All the fields in the `GInitiallyUnowned` structure are private to the + * implementation and should never be accessed directly. */ /** * GInitiallyUnownedClass: @@ -531,7 +539,9 @@ void g_object_remove_weak_pointer (GObject *object, * references. * * A callback function used for notification when the state - * of a toggle reference changes. See g_object_add_toggle_ref(). + * of a toggle reference changes. + * + * See also: g_object_add_toggle_ref() */ typedef void (*GToggleNotify) (gpointer data, GObject *object, @@ -685,10 +695,11 @@ void g_clear_object (GObject **object_ptr); * @new_object: (nullable) (transfer none): a pointer to the new #GObject to * assign to @object_ptr, or %NULL to clear the pointer * - * Updates a #GObject pointer to refer to @new_object. It increments the - * reference count of @new_object (if non-%NULL), decrements the reference - * count of the current value of @object_ptr (if non-%NULL), and assigns - * @new_object to @object_ptr. The assignment is not atomic. + * Updates a #GObject pointer to refer to @new_object. + * + * It increments the reference count of @new_object (if non-%NULL), decrements + * the reference count of the current value of @object_ptr (if non-%NULL), and + * assigns @new_object to @object_ptr. The assignment is not atomic. * * @object_ptr must not be %NULL, but can point to a %NULL value. * @@ -838,13 +849,15 @@ static inline void * @new_object: (nullable) (transfer none): a pointer to the new #GObject to * assign to it, or %NULL to clear the pointer * - * Updates a pointer to weakly refer to @new_object. It assigns @new_object - * to @weak_pointer_location and ensures that @weak_pointer_location will - * automatically be set to %NULL if @new_object gets destroyed. The assignment - * is not atomic. The weak reference is not thread-safe, see - * g_object_add_weak_pointer() for details. + * Updates a pointer to weakly refer to @new_object. * - * @weak_pointer_location must not be %NULL. + * It assigns @new_object to @weak_pointer_location and ensures + * that @weak_pointer_location will automatically be set to %NULL + * if @new_object gets destroyed. The assignment is not atomic. + * The weak reference is not thread-safe, see g_object_add_weak_pointer() + * for details. + * + * The @weak_pointer_location argument must not be %NULL. * * A macro is also included that allows this function to be used without * pointer casts. The function itself is static inline, so its address may vary diff --git a/gobject/gparam.c b/gobject/gparam.c index 2c09f5bd6..b3e4c671f 100644 --- a/gobject/gparam.c +++ b/gobject/gparam.c @@ -890,9 +890,10 @@ value_param_lcopy_value (const GValue *value, * GParamSpecPool: * * A #GParamSpecPool maintains a collection of #GParamSpecs which can be - * quickly accessed by owner and name. The implementation of the #GObject property - * system uses such a pool to store the #GParamSpecs of the properties all object - * types. + * quickly accessed by owner and name. + * + * The implementation of the #GObject property system uses such a pool to + * store the #GParamSpecs of the properties all object types. */ struct _GParamSpecPool { @@ -1401,10 +1402,12 @@ default_values_cmp (GParamSpec *pspec, * @name: 0-terminated string used as the name of the new #GParamSpec type. * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. * - * Registers @name as the name of a new static type derived from - * #G_TYPE_PARAM. The type system uses the information contained in - * the #GParamSpecTypeInfo structure pointed to by @info to manage the - * #GParamSpec type and its instances. + * Registers @name as the name of a new static type derived + * from #G_TYPE_PARAM. + * + * The type system uses the information contained in the #GParamSpecTypeInfo + * structure pointed to by @info to manage the #GParamSpec type and its + * instances. * * Returns: The new type identifier. */ diff --git a/gobject/gparam.h b/gobject/gparam.h index 7294ed515..367d4760f 100644 --- a/gobject/gparam.h +++ b/gobject/gparam.h @@ -145,7 +145,9 @@ G_BEGIN_DECLS * Since 2.26 * * Through the #GParamFlags flag values, certain aspects of parameters - * can be configured. See also #G_PARAM_STATIC_STRINGS. + * can be configured. + * + * See also: %G_PARAM_STATIC_STRINGS */ typedef enum { @@ -368,6 +370,7 @@ typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo; * This structure is used to provide the type system with the information * required to initialize and destruct (finalize) a parameter's class and * instances thereof. + * * The initialized structure is passed to the g_param_type_register_static() * The type system will perform a deep copy of this structure, so its memory * does not need to be persistent across invocation of diff --git a/gobject/gparamspecs.h b/gobject/gparamspecs.h index 9aac2c423..78bf6b82b 100644 --- a/gobject/gparamspecs.h +++ b/gobject/gparamspecs.h @@ -922,12 +922,15 @@ struct _GParamSpecObject }; /** * GParamSpecOverride: + * + * A #GParamSpec derived structure that redirects operations to + * other types of #GParamSpec. * - * This is a type of #GParamSpec type that simply redirects operations to - * another paramspec. All operations other than getting or - * setting the value are redirected, including accessing the nick and - * blurb, validating a value, and so forth. See - * g_param_spec_get_redirect_target() for retrieving the overridden + * All operations other than getting or setting the value are redirected, + * including accessing the nick and blurb, validating a value, and so + * forth. + * + * See g_param_spec_get_redirect_target() for retrieving the overridden * property. #GParamSpecOverride is used in implementing * g_object_class_override_property(), and will not be directly useful * unless you are implementing a new base type similar to GObject. diff --git a/gobject/gsignal.h b/gobject/gsignal.h index b027f54c0..96e4eb38a 100644 --- a/gobject/gsignal.h +++ b/gobject/gsignal.h @@ -36,9 +36,11 @@ typedef struct _GSignalInvocationHint GSignalInvocationHint; * * This is the signature of marshaller functions, required to marshall * arrays of parameter values to signal emissions into C language callback - * invocations. It is merely an alias to #GClosureMarshal since the #GClosure - * mechanism takes over responsibility of actual function invocation for the - * signal system. + * invocations. + * + * It is merely an alias to #GClosureMarshal since the #GClosure mechanism + * takes over responsibility of actual function invocation for the signal + * system. */ typedef GClosureMarshal GSignalCMarshaller; /** @@ -58,9 +60,10 @@ typedef GVaClosureMarshal GSignalCVaMarshaller; * the signal was emitted, followed by the parameters of the emission. * @data: user data associated with the hook. * - * A simple function pointer to get invoked when the signal is emitted. This - * allows you to tie a hook to the signal type, so that it will trap all - * emissions of that signal, from any object. + * A simple function pointer to get invoked when the signal is emitted. + * + * Emission hooks allow you to tie a hook to the signal type, so that it will + * trap all emissions of that signal, from any object. * * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. * @@ -81,10 +84,12 @@ typedef gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint, * * The signal accumulator is a special callback function that can be used * to collect return values of the various callbacks that are called - * during a signal emission. The signal accumulator is specified at signal - * creation time, if it is left %NULL, no accumulation of callback return - * values is performed. The return value of signal emissions is then the - * value returned by the last callback. + * during a signal emission. + * + * The signal accumulator is specified at signal creation time, if it is + * left %NULL, no accumulation of callback return values is performed. + * The return value of signal emissions is then the value returned by the + * last callback. * * Returns: The accumulator function returns whether the signal emission * should be aborted. Returning %TRUE will continue with @@ -126,9 +131,7 @@ typedef gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint, * functions for the #GSignalInvocationHint::run_type field to mark the first * call to the accumulator function for a signal emission. Since 2.68. * - * The signal flags are used to specify a signal's behaviour, the overall - * signal description outlines how especially the RUN flags control the - * stages of a signal emission. + * The signal flags are used to specify a signal's behaviour. */ typedef enum { @@ -253,8 +256,9 @@ struct _GSignalInvocationHint * gpointer data2); * ]| * - * A structure holding in-depth information for a specific signal. It is - * filled in by the g_signal_query() function. + * A structure holding in-depth information for a specific signal. + * + * See also: g_signal_query() */ struct _GSignalQuery { diff --git a/gobject/gtype.c b/gobject/gtype.c index 422e1cae4..34f62ecba 100644 --- a/gobject/gtype.c +++ b/gobject/gtype.c @@ -48,7 +48,7 @@ * management system * @title:Type Information * - * The GType API is the foundation of the GObject system. It provides the + * The GType API is the foundation of the GObject system. It provides the * facilities for registering and managing all fundamental data types, * user-defined object and interface types. * diff --git a/gobject/gtype.h b/gobject/gtype.h index f80c4a580..874a7c00c 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -32,6 +32,7 @@ G_BEGIN_DECLS * @type: A #GType value. * * The fundamental type which is the ancestor of @type. + * * Fundamental types are types that serve as ultimate bases for the derived types, * thus they are the roots of distinct inheritance hierarchies. */ @@ -70,6 +71,7 @@ G_BEGIN_DECLS * G_TYPE_CHAR: * * The fundamental type corresponding to #gchar. + * * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. * This may or may not be the same type a the C type "gchar". */ @@ -213,6 +215,7 @@ G_BEGIN_DECLS * @x: the fundamental type number. * * Get the type ID for the fundamental type number @x. + * * Use g_type_fundamental_next() instead of this macro to create new fundamental * types. * @@ -281,6 +284,7 @@ G_BEGIN_DECLS * @type: A #GType value * * Checks if @type is an interface type. + * * An interface type provides a pure API, the implementation * of which is provided by another type (which is then said to conform * to the interface). GLib interfaces are somewhat analogous to Java @@ -451,7 +455,8 @@ struct _GTypeInterface * @instance_size: the size of the instance structure * * A structure holding information for a specific type. - * It is filled in by the g_type_query() function. + * + * See also: g_type_query() */ struct _GTypeQuery { @@ -642,6 +647,7 @@ struct _GTypeQuery * @c_type: The C type for the private structure * * Gets the private structure for a particular type. + * * The private structure must have been registered in the * class_init function with g_type_class_add_private(). * @@ -661,6 +667,7 @@ struct _GTypeQuery * @c_type: The C type for the private structure * * Gets the private class structure for a particular type. + * * The private structure must have been registered in the * get_type() function with g_type_add_class_private(). * @@ -773,9 +780,12 @@ int g_type_get_instance_count (GType type); * @g_class: (type GObject.TypeClass): The #GTypeClass structure to initialize * * A callback function used by the type system to do base initialization - * of the class structures of derived types. It is called as part of the - * initialization process of all derived classes and should reallocate - * or reset all dynamic class members copied over from the parent class. + * of the class structures of derived types. + * + * This function is called as part of the initialization process of all derived + * classes and should reallocate or reset all dynamic class members copied over + * from the parent class. + * * For example, class members (such as strings) that are not sufficiently * handled by a plain memory copy of the parent class into the derived class * have to be altered. See GClassInitFunc() for a discussion of the class @@ -788,8 +798,11 @@ typedef void (*GBaseInitFunc) (gpointer g_class); * * A callback function used by the type system to finalize those portions * of a derived types class structure that were setup from the corresponding - * GBaseInitFunc() function. Class finalization basically works the inverse - * way in which class initialization is performed. + * GBaseInitFunc() function. + * + * Class finalization basically works the inverse way in which class + * initialization is performed. + * * See GClassInitFunc() for a discussion of the class initialization process. */ typedef void (*GBaseFinalizeFunc) (gpointer g_class); @@ -799,8 +812,9 @@ typedef void (*GBaseFinalizeFunc) (gpointer g_class); * @class_data: The @class_data member supplied via the #GTypeInfo structure. * * A callback function used by the type system to initialize the class - * of a specific type. This function should initialize all static class - * members. + * of a specific type. + * + * This function should initialize all static class members. * * The initialization process of a class involves: * @@ -869,6 +883,7 @@ typedef void (*GBaseFinalizeFunc) (gpointer g_class); * class->static_float = 3.14159265358979323846; * } * ]| + * * Initialization of TypeBClass will first cause initialization of * TypeAClass (derived classes reference their parent classes, see * g_type_class_ref() on this). @@ -902,8 +917,10 @@ typedef void (*GClassInitFunc) (gpointer g_class, * @class_data: The @class_data member supplied via the #GTypeInfo structure * * A callback function used by the type system to finalize a class. + * * This function is rarely needed, as dynamically allocated class resources * should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). + * * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo * structure of a static type is invalid, because classes of static types * will never be finalized (they are artificially kept alive when their @@ -918,8 +935,10 @@ typedef void (*GClassFinalizeFunc) (gpointer g_class, * created for * * A callback function used by the type system to initialize a new - * instance of a type. This function initializes all instance members and - * allocates any resources required by it. + * instance of a type. + * + * This function initializes all instance members and allocates any resources + * required by it. * * Initialization of a derived instance involves calling all its parent * types instance initializers, so the class member of the instance @@ -937,8 +956,10 @@ typedef void (*GInstanceInitFunc) (GTypeInstance *instance, * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure * * A callback function used by the type system to initialize a new - * interface. This function should initialize all internal data and - * allocate any resources required by the interface. + * interface. + * + * This function should initialize all internal data and* allocate any + * resources required by the interface. * * The members of @iface_data are guaranteed to have been filled with * zeros before this function is called. @@ -951,6 +972,7 @@ typedef void (*GInterfaceInitFunc) (gpointer g_iface, * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure * * A callback function used by the type system to finalize an interface. + * * This function should destroy any internal data and release any resources * allocated by the corresponding GInterfaceInitFunc() function. */ @@ -963,10 +985,11 @@ typedef void (*GInterfaceFinalizeFunc) (gpointer g_iface, * unreferenced * * A callback function which is called when the reference count of a class - * drops to zero. It may use g_type_class_ref() to prevent the class from - * being freed. You should not call g_type_class_unref() from a - * #GTypeClassCacheFunc function to prevent infinite recursion, use - * g_type_class_unref_uncached() instead. + * drops to zero. + * + * It may use g_type_class_ref() to prevent the class from being freed. You + * should not call g_type_class_unref() from a #GTypeClassCacheFunc function + * to prevent infinite recursion, use g_type_class_unref_uncached() instead. * * The functions have to check the class id passed in to figure * whether they actually want to cache the class of this type, since all @@ -984,6 +1007,7 @@ typedef gboolean (*GTypeClassCacheFunc) (gpointer cache_data, * initialized * * A callback called after an interface vtable is initialized. + * * See g_type_add_interface_check(). * * Since: 2.4 @@ -1356,12 +1380,12 @@ guint g_type_get_type_registration_serial (void); * @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`) * @ParentName: the name of the parent type, in camel case (like `GtkWidget`) * - * A convenience macro for emitting the usual declarations in the header file for a type which is not (at the - * present time) intended to be subclassed. + * A convenience macro for emitting the usual declarations in the header file + * for a type which is not (at the present time) intended to be subclassed. * * You might use it in a header as follows: * - * |[ + * |[ * #ifndef _myapp_window_h_ * #define _myapp_window_h_ * @@ -1442,7 +1466,7 @@ guint g_type_get_type_registration_serial (void); * * You might use it in a header as follows: * - * |[ + * |[ * #ifndef _gtk_frobber_h_ * #define _gtk_frobber_h_ * @@ -1539,7 +1563,7 @@ guint g_type_get_type_registration_serial (void); * * You might use it in a header as follows: * - * |[ + * |[ * #ifndef _my_model_h_ * #define _my_model_h_ * @@ -1623,7 +1647,8 @@ guint g_type_get_type_registration_serial (void); * @T_P: The #GType of the parent type. * @_C_: Custom code that gets inserted in the `*_get_type()` function. * - * A convenience macro for type implementations. + * A convenience macro for type implementations. + * * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the * `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). * See G_DEFINE_TYPE_EXTENDED() for an example. @@ -1642,6 +1667,7 @@ guint g_type_get_type_registration_serial (void); * initialization function, an instance initialization function (see #GTypeInfo * for information about these), a static variable named `t_n_parent_class` * pointing to the parent class, and adds private instance data to the type. + * * Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED() * for an example. * @@ -1663,8 +1689,9 @@ guint g_type_get_type_registration_serial (void); * separated by `_`. * @T_P: The #GType of the parent type. * - * A convenience macro for type implementations. - * Similar to G_DEFINE_TYPE(), but defines an abstract type. + * A convenience macro for type implementations. + * + * Similar to G_DEFINE_TYPE(), but defines an abstract type. * See G_DEFINE_TYPE_EXTENDED() for an example. * * Since: 2.4 @@ -1679,9 +1706,11 @@ guint g_type_get_type_registration_serial (void); * @_C_: Custom code that gets inserted in the `type_name_get_type()` function. * * A convenience macro for type implementations. + * * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and * allows you to insert custom code into the `*_get_type()` function, e.g. * interface implementations via G_IMPLEMENT_INTERFACE(). + * * See G_DEFINE_TYPE_EXTENDED() for an example. * * Since: 2.4 @@ -1694,7 +1723,8 @@ guint g_type_get_type_registration_serial (void); * separated by `_`. * @T_P: The #GType of the parent type. * - * Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. + * Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. + * * See G_DEFINE_TYPE_EXTENDED() for an example. * * Since: 2.38 @@ -1772,7 +1802,9 @@ guint g_type_get_type_registration_serial (void); * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, * gtk_gadget_gizmo_init)); * ]| + * * expands to + * * |[ * static void gtk_gadget_init (GtkGadget *self); * static void gtk_gadget_class_init (GtkGadgetClass *klass); @@ -1819,6 +1851,7 @@ guint g_type_get_type_registration_serial (void); * return static_g_define_type_id; * } * ]| + * * The only pieces which have to be manually provided are the definitions of * the instance and class structure and the definitions of the instance and * class init functions. @@ -1860,11 +1893,13 @@ guint g_type_get_type_registration_serial (void); * for no prerequisite type. * @_C_: Custom code that gets inserted in the `*_get_type()` function. * - * A convenience macro for #GTypeInterface definitions. Similar to - * G_DEFINE_INTERFACE(), but allows you to insert custom code into the - * `*_get_type()` function, e.g. additional interface implementations - * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See - * G_DEFINE_TYPE_EXTENDED() for a similar example using + * A convenience macro for #GTypeInterface definitions. + * + * Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code + * into the `*_get_type()` function, e.g. additional interface implementations + * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. + * + * See G_DEFINE_TYPE_EXTENDED() for a similar example using * G_DEFINE_TYPE_WITH_CODE(). * * Since: 2.24 @@ -2153,7 +2188,6 @@ type_name##_get_type (void) \ * GType type = my_struct_get_type (); * // ... your code ... * } - * * ]| * * Since: 2.26 @@ -2169,6 +2203,7 @@ type_name##_get_type (void) \ * @_C_: Custom code that gets inserted in the `*_get_type()` function * * A convenience macro for boxed type implementations. + * * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the * `type_name_get_type()` function, e.g. to register value transformations with * g_value_register_transform_func(), for instance: diff --git a/gobject/gtypemodule.c b/gobject/gtypemodule.c index 014b5fc3c..1c2ab43ea 100644 --- a/gobject/gtypemodule.c +++ b/gobject/gtypemodule.c @@ -30,16 +30,20 @@ * @title: GTypeModule * * #GTypeModule provides a simple implementation of the #GTypePlugin - * interface. The model of #GTypeModule is a dynamically loaded module - * which implements some number of types and interface implementations. + * interface. + * + * The model of #GTypeModule is a dynamically loaded module which + * implements some number of types and interface implementations. + * * When the module is loaded, it registers its types and interfaces * using g_type_module_register_type() and g_type_module_add_interface(). * As long as any instances of these types and interface implementations * are in use, the module is kept loaded. When the types and interfaces * are gone, the module may be unloaded. If the types and interfaces * become used again, the module will be reloaded. Note that the last - * unref cannot happen in module code, since that would lead to the - * caller's code being unloaded before g_object_unref() returns to it. + * reference cannot be released from within the module code, since that + * would lead to the caller's code being unloaded before g_object_unref() + * returns to it. * * Keeping track of whether the module should be loaded or not is done by * using a use count - it starts at zero, and whenever it is greater than @@ -57,7 +61,6 @@ * in #GTypeModuleClass. */ - typedef struct _ModuleTypeInfo ModuleTypeInfo; typedef struct _ModuleInterfaceInfo ModuleInterfaceInfo; diff --git a/gobject/gtypemodule.h b/gobject/gtypemodule.h index 5c4025063..400d7f1b0 100644 --- a/gobject/gtypemodule.h +++ b/gobject/gtypemodule.h @@ -93,9 +93,10 @@ struct _GTypeModuleClass * A convenience macro for dynamic type implementations, which declares a * class initialization function, an instance initialization function (see * #GTypeInfo for information about these) and a static variable named - * `t_n`_parent_class pointing to the parent class. Furthermore, - * it defines a `*_get_type()` and a static `*_register_type()` functions - * for use in your `module_init()`. + * `t_n`_parent_class pointing to the parent class. + * + * Furthermore, it defines a `*_get_type()` and a static `*_register_type()` + * functions for use in your `module_init()`. * * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. * @@ -114,7 +115,7 @@ struct _GTypeModuleClass * A more general version of G_DEFINE_DYNAMIC_TYPE() which * allows to specify #GTypeFlags and custom code. * - * |[ + * |[ * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, * gtk_gadget, * GTK_TYPE_THING, @@ -122,8 +123,10 @@ struct _GTypeModuleClass * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, * gtk_gadget_gizmo_init)); * ]| + * * expands to - * |[ + * + * |[ * static void gtk_gadget_init (GtkGadget *self); * static void gtk_gadget_class_init (GtkGadgetClass *klass); * static void gtk_gadget_class_finalize (GtkGadgetClass *klass); @@ -227,8 +230,9 @@ type_name##_register_type (GTypeModule *type_module) \ * @iface_init: The interface init function * * A convenience macro to ease interface addition in the @_C_ section - * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() - * for an example. + * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). + * + * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. * * Note that this macro can only be used together with the * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable @@ -248,8 +252,9 @@ type_name##_register_type (GTypeModule *type_module) \ * @TypeName: the name of the type in CamelCase * * A convenience macro to ease adding private data to instances of a new dynamic - * type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See - * G_ADD_PRIVATE() for details, it is similar but for static types. + * type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). + * + * See G_ADD_PRIVATE() for details, it is similar but for static types. * * Note that this macro can only be used together with the * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable diff --git a/gobject/gtypeplugin.c b/gobject/gtypeplugin.c index eba85151d..30e38c1a9 100644 --- a/gobject/gtypeplugin.c +++ b/gobject/gtypeplugin.c @@ -26,9 +26,10 @@ * @see_also: #GTypeModule and g_type_register_dynamic(). * @title: GTypePlugin * + * An interface that handles the lifecycle of dynamically loaded types. + * * The GObject type system supports dynamic loading of types. - * The #GTypePlugin interface is used to handle the lifecycle - * of dynamically loaded types. It goes as follows: + * It goes as follows: * * 1. The type is initially introduced (usually upon loading the module * the first time, or by your main application that knows what modules diff --git a/gobject/gvalue.c b/gobject/gvalue.c index 797aa186b..097755069 100644 --- a/gobject/gvalue.c +++ b/gobject/gvalue.c @@ -42,6 +42,7 @@ * * The #GValue structure is basically a variable container that consists * of a type identifier and a specific value of that type. + * * The type identifier within a #GValue structure always determines the * type of the associated value. * diff --git a/gobject/gvalue.h b/gobject/gvalue.h index dc6e5ac3b..3630c0b53 100644 --- a/gobject/gvalue.h +++ b/gobject/gvalue.h @@ -33,6 +33,7 @@ G_BEGIN_DECLS * @type: A #GType value. * * Checks whether the passed in type ID can be used for g_value_init(). + * * That is, this macro checks whether this type provides an implementation * of the #GTypeValueTable functions required for a type to create a #GValue of. * @@ -97,10 +98,12 @@ typedef void (*GValueTransform) (const GValue *src_value, * GValue: * * An opaque structure used to hold different types of values. + * * The data within the structure has protected scope: it is accessible only * to functions within a #GTypeValueTable structure, or implementations of * the g_value_*() API. That is, code portions which implement new fundamental * types. + * * #GValue users cannot make any assumptions about how data is stored * within the 2 element @data union, and the @g_type member should * only be accessed through the G_VALUE_TYPE() macro. @@ -193,7 +196,7 @@ void g_value_register_transform_func (GType src_type, * be used as initializer instead of an explicit `{ 0 }` when declaring * a variable, but it cannot be assigned to a variable. * - * |[ + * |[ * GValue value = G_VALUE_INIT; * ]| * diff --git a/gobject/gvaluecollector.h b/gobject/gvaluecollector.h index b1304595f..2714b36a7 100644 --- a/gobject/gvaluecollector.h +++ b/gobject/gvaluecollector.h @@ -23,6 +23,7 @@ * * The macros in this section provide the varargs parsing support needed * in variadic GObject functions such as g_object_new() or g_object_set(). + * * They currently support the collection of integral types, floating point * types and pointers. */ @@ -79,9 +80,10 @@ union _GTypeCValue * @__error: a #gchar** variable that will be modified to hold a g_new() * allocated error messages if something fails * - * Collects a variable argument value from a va_list. We have to - * implement the varargs collection as a macro, because on some systems - * va_list variables cannot be passed by reference. + * Collects a variable argument value from a `va_list`. + * + * We have to implement the varargs collection as a macro, because on some + * systems `va_list` variables cannot be passed by reference. * * Since: 2.24 */ @@ -136,9 +138,10 @@ G_STMT_START { \ * @__error: a #gchar** variable that will be modified to hold a g_new() * allocated error messages if something fails * - * Collects a variable argument value from a va_list. We have to - * implement the varargs collection as a macro, because on some systems - * va_list variables cannot be passed by reference. + * Collects a variable argument value from a `va_list`. + * + * We have to implement the varargs collection as a macro, because on some systems + * `va_list` variables cannot be passed by reference. * * Note: If you are creating the @value argument just before calling this macro, * you should use the #G_VALUE_COLLECT_INIT variant and pass the uninitialized @@ -203,7 +206,8 @@ G_STMT_START { \ * @__error: a #gchar** variable that will be modified to hold a g_new() * allocated error message if something fails * - * Stores a value’s value into one or more argument locations from a va_list. + * Stores a value’s value into one or more argument locations from a `va_list`. + * * This is the inverse of G_VALUE_COLLECT(). */ #define G_VALUE_LCOPY(value, var_args, flags, __error) \