luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'docgen-fixes' into 'main'

Browse Source 
Adapt documentation to gi-docgen

See merge request GNOME/glib!2206
This commit is contained in:
Philip Withnall 2021-08-03 13:53:38 +00:00
commit 709df8eeb4
45 changed files with 893 additions and 539 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/reference/gio/gio-docs.xml
View File

@ -48,8 +48,8 @@
<title>Data conversion</title>
<xi:include href="xml/gconverter.xml"/>
<xi:include href="xml/gcharsetconverter.xml"/>
<xi:include href="xml/gzcompressor.xml"/>
<xi:include href="xml/gzdecompressor.xml"/>
<xi:include href="xml/gzlibcompressor.xml"/>
<xi:include href="xml/gzlibdecompressor.xml"/>
</chapter>
<chapter id="streaming">
<title>Streaming I/O</title>

4
docs/reference/gio/gio-sections-common.txt
View File

@ -2505,7 +2505,7 @@ g_converter_output_stream_get_type
</SECTION>
<SECTION>
<FILE>gzcompressor</FILE>
<FILE>gzlibcompressor</FILE>
<TITLE>GZlibCompressor</TITLE>
GZlibCompressor
GZlibCompressorFormat
@ -2527,7 +2527,7 @@ g_zlib_compressor_format_get_type
</SECTION>
<SECTION>
<FILE>gzdecompressor</FILE>
<FILE>gzlibdecompressor</FILE>
<TITLE>GZlibDecompressor</TITLE>
GZlibDecompressor
g_zlib_decompressor_new

375
gio/gfileinfo.h
View File

@ -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
**/

15
gio/gmemorymonitor.c
View File

@ -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

2
gio/gzlibcompressor.c
View File

@ -41,7 +41,7 @@ enum {
};
/**
* SECTION:gzcompressor
* SECTION:gzlibcompressor
* @short_description: Zlib compressor
* @include: gio/gio.h
*

2
gio/gzlibdecompressor.c
View File

@ -40,7 +40,7 @@ enum {
};
/**
* SECTION:gzdecompressor
* SECTION:gzlibdecompressor
* @short_description: Zlib decompressor
* @include: gio/gio.h
*

6
glib/gasyncqueue.c
View File

@ -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
{

4
glib/gbookmarkfile.h
View File

@ -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;

1
glib/gchecksum.h
View File

@ -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().
*

6
glib/gdataset.c
View File

@ -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].
**/
/**

31
glib/gdate.c
View File

@ -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:
*
* |[<!-- language="C" -->
* 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.
*/
/**

3
glib/gdatetime.h
View File

@ -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
*/

5
glib/gfileutils.c
View File

@ -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)

24
glib/gfileutils.h
View File

@ -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.

77
glib/gkeyfile.c
View File

@ -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

79
glib/gmain.c
View File

@ -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().
*

50
glib/gmessages.c
View File

@ -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:
*
* |[<!-- language="C" -->
* 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+:
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* const GLogField fields[] = {
* { "MESSAGE", "This is a debug message.", -1 },

3
glib/gmessages.h
View File

@ -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,

78
glib/gshell.c
View File

@ -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
**/

15
glib/gslice.c
View File

@ -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
*/

108
glib/gspawn.c
View File

@ -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
*/

25
glib/gstrfuncs.c
View File

@ -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:
*
* |[<!-- language="C" -->
* 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():
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* 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():
*
* |[<!-- language="C" -->
* reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
* ...
* g_free (reformatted);
* ]|
*
* Returns: @string
* Returns: the modified @string
*/
gchar *
g_strcanon (gchar *string,

19
glib/gthread.c
View File

@ -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:
* |[<!-- language="C" -->
* 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 ------------------------------------------ */

13
glib/gunicode.h
View File

@ -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.
*/

9
glib/gvariant.h
View File

@ -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.
*
* |[
* |[<!-- language="C" -->
* 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().
*
* |[
* |[<!-- language="C" -->
* g_autoptr(GVariant) variant = get_asv_variant ();
* g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant);
* ]|

25
glib/gversion.c
View File

@ -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
*/

15
gobject/gbinding.c
View File

@ -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).
*
* |[<!-- language="C" -->
* Whenever the source property changes, the same value is applied to the
* target property; for instance, the following binding:
*
* |[<!-- language="C" -->
* 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:
*
* |[
* |[<!-- language="C" -->
* g_object_bind_property (action, "active", widget, "sensitive", 0);
* ]|
*

5
gobject/gbinding.h
View File

@ -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,

16
gobject/gboxed.c
View File

@ -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.
*/

92
gobject/gclosure.c
View File

@ -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:
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* 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,

12
gobject/gclosure.h
View File

@ -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);
/**

17
gobject/gobject.c
View File

@ -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:
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* 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:
*
* |[<!-- language="C" -->
* 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.

59
gobject/gobject.h
View File

@ -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

17
gobject/gparam.c
View File

@ -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.
*/

5
gobject/gparam.h
View File

@ -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

13
gobject/gparamspecs.h
View File

@ -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.

34
gobject/gsignal.h
View File

@ -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
{

2
gobject/gtype.c
View File

@ -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.
*

97
gobject/gtype.h
View File

@ -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:
*
* |[
* |[<!-- language="C" -->
* #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:
*
* |[
* |[<!-- language="C" -->
* #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:
*
* |[
* |[<!-- language="C" -->
* #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
*
* |[<!-- language="C" -->
* 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:

13
gobject/gtypemodule.c
View File

@ -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;

23
gobject/gtypemodule.h
View File

@ -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.
*
* |[
* |[<!-- language="C" -->
* 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
* |[
*
* |[<!-- language="C" -->
* 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

5
gobject/gtypeplugin.c
View File

@ -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

1
gobject/gvalue.c
View File

@ -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.
*

5
gobject/gvalue.h
View File

@ -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.
*
* |[
* |[<!-- language="C" -->
* GValue value = G_VALUE_INIT;
* ]|
*

18
gobject/gvaluecollector.h
View File

@ -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) \