luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 11:26:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'migrate-to-gi-docgen5' into 'main'

Browse Source 
Switch to using gi-docgen for docs (batch 5)

See merge request GNOME/glib!3660
This commit is contained in:
Philip Withnall 2023-10-23 13:00:58 +00:00
commit 0647927a65
43 changed files with 407 additions and 516 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
docs/reference/gio/file-attributes.md Normal file
View File

@ -0,0 +1,111 @@
Title: File Attributes
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Andrew Walton
SPDX-FileCopyrightText: 2007 Alexander Larsson
SPDX-FileCopyrightText: 2008, 2014 Matthias Clasen
SPDX-FileCopyrightText: 2011 Murray Cumming
SPDX-FileCopyrightText: 2012 David King
# File Attributes
File attributes in GIO consist of a list of key-value pairs.
Keys are strings that contain a key namespace and a key name, separated
by a colon, e.g. `namespace::keyname`. Namespaces are included to sort
key-value pairs by namespaces for relevance. Keys can be retrieved
using wildcards, e.g. `standard::*` will return all of the keys in the
`standard` namespace.
The list of possible attributes for a filesystem (pointed to by a
[iface@Gio.File]) is available as a [struct@Gio.FileAttributeInfoList]. This
list is queryable by key names as indicated earlier.
Information is stored within the list in [struct@Gio.FileAttributeInfo]
structures. The info structure can store different types, listed in the enum
[type@Gio.FileAttributeType]. Upon creation of a [struct@Gio.FileAttributeInfo],
the type will be set to `G_FILE_ATTRIBUTE_TYPE_INVALID`.
Classes that implement [iface@Gio.File] will create a
[struct@Gio.FileAttributeInfoList] and install default keys and values for their
given file system, architecture, and other possible implementation details
(e.g., on a UNIX system, a file attribute key will be registered for the user ID
for a given file).
## Default Namespaces
- `"standard"`: The ‘Standard’ namespace. General file information that
any application may need should be put in this namespace. Examples
include the file’s name, type, and size.
- `"etag`: The [Entity Tag](gfile.html#entity-tags) namespace. Currently, the
only key in this namespace is `value`, which contains the value of the current
entity tag.
- `"id"`: The ‘Identification’ namespace. This namespace is used by file
managers and applications that list directories to check for loops and
to uniquely identify files.
- `"access"`: The ‘Access’ namespace. Used to check if a user has the
proper privileges to access files and perform file operations. Keys in
this namespace are made to be generic and easily understood, e.g. the
`can_read` key is true if the current user has permission to read the
file. UNIX permissions and NTFS ACLs in Windows should be mapped to
these values.
- `"mountable"`: The ‘Mountable’ namespace. Includes simple boolean keys
for checking if a file or path supports mount operations, e.g. mount,
unmount, eject. These are used for files of type `G_FILE_TYPE_MOUNTABLE`.
- `"time"`: The ‘Time’ namespace. Includes file access, changed, created
times.
- `"unix"`: The ‘Unix’ namespace. Includes UNIX-specific information and
may not be available for all files. Examples include the UNIX UID,
GID, etc.
- `"dos"`: The ‘DOS’ namespace. Includes DOS-specific information and may
not be available for all files. Examples include `is_system` for checking
if a file is marked as a system file, and `is_archive` for checking if a
file is marked as an archive file.
- `"owner"`: The ‘Owner’ namespace. Includes information about who owns a
file. May not be available for all file systems. Examples include `user`
for getting the user name of the file owner. This information is often
mapped from some backend specific data such as a UNIX UID.
- `"thumbnail"`: The ‘Thumbnail’ namespace. Includes information about file
thumbnails and their location within the file system. Examples of keys in
this namespace include `path` to get the location of a thumbnail, `failed`
to check if thumbnailing of the file failed, and `is-valid` to check if
the thumbnail is outdated.
- `"filesystem"`: The ‘Filesystem’ namespace. Gets information about the
file system where a file is located, such as its type, how much space is
left available, and the overall size of the file system.
- `"gvfs"`: The ‘GVFS’ namespace. Keys in this namespace contain information
about the current GVFS backend in use.
- `"xattr"`: The ‘xattr’ namespace. Gets information about extended user
attributes. See [`attr(5)`](man:attr(5)). The `user.` prefix of the extended
user attribute name is stripped away when constructing keys in this namespace,
e.g. `xattr::mime_type` for the extended attribute with the name
`user.mime_type`. Note that this information is only available if
GLib has been built with extended attribute support.
- `"xattr-sys"`: The ‘xattr-sys’ namespace. Gets information about
extended attributes which are not user-specific. See [`attr(5)`](man:attr(5)).
Note that this information is only available if GLib has been built with
extended attribute support.
- `"selinux"`: The ‘SELinux’ namespace. Includes information about the
SELinux context of files. Note that this information is only available
if GLib has been built with SELinux support.
Please note that these are not all of the possible namespaces.
More namespaces can be added from GIO modules or by individual applications.
For more information about writing GIO modules, see [class@Gio.IOModule].
<!-- TODO: Implementation note about using extended attributes on supported
file systems -->
## Default Keys
For a list of the built-in keys and their types, see the [class@Gio.FileInfo]
documentation.
Note that there are no predefined keys in the `xattr` and `xattr-sys`
namespaces. Keys for the `xattr` namespace are constructed by stripping
away the `user.` prefix from the extended user attribute, and prepending
`xattr::`. Keys for the `xattr-sys` namespace are constructed by
concatenating `xattr-sys::` with the extended attribute name. All extended
attribute values are returned as hex-encoded strings in which bytes outside
the ASCII range are encoded as escape sequences of the form `\xnn`
where `nn` is a 2-digit hexadecimal number.

1
docs/reference/gio/gio.toml.in
View File

@ -41,6 +41,7 @@ urlmap_file = "urlmap.js"
# The same order will be used when generating the index
content_files = [
"overview.md",
"file-attributes.md",
"migrating-gdbus.md",
"migrating-gconf.md",

1
docs/reference/gio/meson.build
View File

@ -229,6 +229,7 @@ endif
# gi-docgen version
expand_content_files = [
'file-attributes.md',
'migrating-gconf.md',
'migrating-gdbus.md',
'migrating-gnome-vfs.md',

1
docs/reference/gio/urlmap.js
View File

@ -1,6 +1,7 @@
// SPDX-License-Identifier: LGPL-2.1-or-later
// SPDX-FileCopyrightText: 2023 Matthias Clasen
var baseURLs = [
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GModule', 'https://docs.gtk.org/gmodule/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],

1
docs/reference/gobject/gobject.toml.in
View File

@ -50,6 +50,7 @@ content_files = [
"boxed.md",
"enum-types.md",
"gvalue.md",
"value-collection.md",
]
content_images = [
"images/glue.png",

1
docs/reference/gobject/meson.build
View File

@ -74,6 +74,7 @@ expand_content_files = [
'tutorial.md',
'types.md',
'signals.md',
'value-collection.md',
]
gobject_toml = configure_file(input: 'gobject.toml.in', output: 'gobject.toml', configuration: toml_conf)

56
docs/reference/gobject/value-collection.md Normal file
View File

@ -0,0 +1,56 @@
Title: Value Collection
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2005 Matthias Clasen
# Value Collection
GLib provides a set of macros for the varargs parsing support needed
in variadic GObject functions such as [ctor@GObject.Object.new] or
[method@GObject.Object.set]
They currently support the collection of integral types, floating point
types and pointers.
## Macros
`G_VALUE_COLLECT_INIT(value, _value_type, var_args, flags, __error)`
: 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
`G_VALUE_COLLECT_INIT2(value, g_vci_vtab, _value_type, var_args, flags, __error)`
: A variant of `G_VALUE_COLLECT_INIT` that provides the [struct@GObject.TypeValueTable]
to the caller.
Since: 2.74
`G_VALUE_COLLECT(value, var_args, flags, __error)`
: 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
`GValue`. That variant is faster than `G_VALUE_COLLECT`.
`G_VALUE_COLLECT_SKIP(_value_type, var_args)`
: Skip an argument of type `_value_type` from `var_args`.
`G_VALUE_LCOPY(value, var_args, flags, __error)`
: Stores a value’s value into one or more argument locations from a `va_list`.
This is the inverse of G_VALUE_COLLECT().
`G_VALUE_COLLECT_FORMAT_MAX_LENGTH`
: The maximal number of [type@GObject.TypeCValue]s which can be collected for a
single `GValue`.

12
gio/gactiongroupexporter.c
View File

@ -32,18 +32,14 @@
#include "gdbuserror.h"
/**
* SECTION:gactiongroupexporter
* @title: GActionGroup exporter
* @include: gio/gio.h
* @short_description: Export GActionGroups on D-Bus
* @see_also: #GActionGroup, #GDBusActionGroup
* GActionGroupExporter:
*
* These functions support exporting a #GActionGroup on D-Bus.
* These functions support exporting a [class@Gio.ActionGroup] on D-Bus.
* The D-Bus interface that is used is a private implementation
* detail.
*
* To access an exported #GActionGroup remotely, use
* g_dbus_action_group_get() to obtain a #GDBusActionGroup.
* To access an exported `GActionGroup` remotely, use
* [method@Gio.DBusActionGroup.get] to obtain a [class@Gio.DBusActionGroup].
*/
static GVariant *

8
gio/gasynchelper.c
View File

@ -26,14 +26,10 @@
/*< private >
* SECTION:gasynchelper
* @short_description: Asynchronous Helper Functions
* @include: gio/gio.h
* @see_also: #GAsyncResult
* GAsyncHelper:
*
* Provides helper functions for asynchronous operations.
*
**/
*/
#ifdef G_OS_WIN32
gboolean

4
gio/gcontenttype.c
View File

@ -38,9 +38,7 @@
/**
* SECTION:gcontenttype
* @short_description: Platform-specific content typing
* @include: gio/gio.h
* GContentType:
*
* A content type is a platform specific string that defines the type
* of a file. On UNIX it is a

5
gio/gdbusaddress.c
View File

@ -62,10 +62,7 @@
#include "glibintl.h"
/**
* SECTION:gdbusaddress
* @title: D-Bus Addresses
* @short_description: D-Bus connection endpoints
* @include: gio/gio.h
* GDBusAddress:
*
* Routines for working with D-Bus addresses. A D-Bus address is a string
* like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses

14
gio/gdbusmessage.c
View File

@ -462,16 +462,6 @@ g_memory_buffer_put_string (GMemoryBuffer *mbuf,
return g_memory_buffer_write (mbuf, str, strlen (str));
}
/**
* SECTION:gdbusmessage
* @short_description: D-Bus Message
* @include: gio/gio.h
*
* A type for representing D-Bus messages that can be sent or received
* on a #GDBusConnection.
*/
typedef struct _GDBusMessageClass GDBusMessageClass;
/**
@ -490,8 +480,8 @@ struct _GDBusMessageClass
/**
* GDBusMessage:
*
* The #GDBusMessage structure contains only private data and should
* only be accessed using the provided API.
* A type for representing D-Bus messages that can be sent or received
* on a [class@Gio.DBusConnection].
*
* Since: 2.26
*/

20
gio/gdebugcontroller.c
View File

@ -29,25 +29,23 @@
#include "giomodule-priv.h"
/**
* SECTION:gdebugcontroller
* @title: GDebugController
* @short_description: Debugging controller
* @include: gio/gio.h
* GDebugController:
*
* #GDebugController is an interface to expose control of debugging features and
* `GDebugController` is an interface to expose control of debugging features and
* debug output.
*
* It is implemented on Linux using #GDebugControllerDBus, which exposes a D-Bus
* interface to allow authenticated peers to control debug features in this
* process.
* It is implemented on Linux using [class@Gio.DebugControllerDBus], which
* exposes a D-Bus interface to allow authenticated peers to control debug
* features in this process.
*
* Whether debug output is enabled is exposed as
* #GDebugController:debug-enabled. This controls g_log_set_debug_enabled() by
* default. Application code may connect to the #GObject::notify signal for it
* [property@Gio.DebugController:debug-enabled]. This controls
* [func@GLib.log_set_debug_enabled] by default. Application code may
* connect to the [signal@GObject.Object::notify] signal for it
* to control other parts of its debug infrastructure as necessary.
*
* If your application or service is using the default GLib log writer function,
* creating one of the built-in implementations of #GDebugController should be
* creating one of the built-in implementations of `GDebugController` should be
* all that’s needed to dynamically enable or disable debug output.
*
* Since: 2.72

8
gio/gdebugcontroller.h
View File

@ -41,14 +41,6 @@ G_BEGIN_DECLS
*/
#define G_DEBUG_CONTROLLER_EXTENSION_POINT_NAME "gio-debug-controller"
/**
* GDebugController:
*
* #GDebugController is an interface to expose control of debugging features and
* debug output.
*
* Since: 2.72
*/
#define G_TYPE_DEBUG_CONTROLLER (g_debug_controller_get_type ())
GIO_AVAILABLE_IN_2_72
G_DECLARE_INTERFACE(GDebugController, g_debug_controller, g, debug_controller, GObject)

24
gio/gdrive.c
View File

@ -31,36 +31,34 @@
/**
* SECTION:gdrive
* @short_description: Drive management
* @include: gio/gio.h
* GDrive:
*
* #GDrive - this represent a piece of hardware connected to the machine.
* It's generally only created for removable hardware or hardware with
* `GDrive` represents a piece of hardware connected to the machine.
* It’s generally only created for removable hardware or hardware with
* removable media.
*
* #GDrive is a container class for #GVolume objects that stem from
* the same piece of media. As such, #GDrive abstracts a drive with
* `GDrive` is a container class for [class@Gio.Volume] objects that stem from
* the same piece of media. As such, `GDrive` abstracts a drive with
* (or without) removable media and provides operations for querying
* whether media is available, determining whether media change is
* automatically detected and ejecting the media.
*
* If the #GDrive reports that media isn't automatically detected, one
* If the `GDrive` reports that media isn’t automatically detected, one
* can poll for media; typically one should not do this periodically
* as a poll for media operation is potentially expensive and may
* spin up the drive creating noise.
*
* #GDrive supports starting and stopping drives with authentication
* `GDrive` supports starting and stopping drives with authentication
* support for the former. This can be used to support a diverse set
* of use cases including connecting/disconnecting iSCSI devices,
* powering down external disk enclosures and starting/stopping
* multi-disk devices such as RAID devices. Note that the actual
* semantics and side-effects of starting/stopping a #GDrive may vary
* semantics and side-effects of starting/stopping a `GDrive` may vary
* according to implementation. To choose the correct verbs in e.g. a
* file manager, use g_drive_get_start_stop_type().
* file manager, use [method@Gio.Drive.get_start_stop_type].
*
* For porting from GnomeVFS note that there is no equivalent of
* #GDrive in that API.
* For [porting from GnomeVFS](migrating-gnome-vfs.html) note that there is no
* equivalent of `GDrive` in that API.
**/
typedef GDriveIface GDriveInterface;

16
gio/gdtlsclientconnection.c
View File

@ -31,26 +31,14 @@
#include "gtlscertificate.h"
#include "glibintl.h"
/**
* SECTION:gdtlsclientconnection
* @short_description: DTLS client-side connection
* @include: gio/gio.h
*
* #GDtlsClientConnection is the client-side subclass of
* #GDtlsConnection, representing a client-side DTLS connection.
*
* Since: 2.48
*/
/**
* GDtlsClientConnection:
*
* Abstract base class for the backend-specific client connection
* type.
* `GDtlsClientConnection` is the client-side subclass of
* [iface@Gio.DtlsConnection], representing a client-side DTLS connection.
*
* Since: 2.48
*/
G_DEFINE_INTERFACE (GDtlsClientConnection, g_dtls_client_connection,
G_TYPE_DTLS_CONNECTION)

52
gio/gdtlsconnection.c
View File

@ -35,43 +35,33 @@
#include "glibintl.h"
#include "gmarshal-internal.h"
/**
* SECTION:gdtlsconnection
* @short_description: DTLS connection type
* @include: gio/gio.h
*
* #GDtlsConnection is the base DTLS connection class type, which wraps
* a #GDatagramBased and provides DTLS encryption on top of it. Its
* subclasses, #GDtlsClientConnection and #GDtlsServerConnection,
* implement client-side and server-side DTLS, respectively.
*
* For TLS support, see #GTlsConnection.
*
* As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased,
* presenting a datagram-socket-like API for the encrypted connection. This
* operates over a base datagram connection, which is also a #GDatagramBased
* (#GDtlsConnection:base-socket).
*
* To close a DTLS connection, use g_dtls_connection_close().
*
* Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address
* on their base #GDatagramBased if it is a #GSocket — it is up to the caller to
* do that if they wish. If they do not, and g_socket_close() is called on the
* base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED
* error on further I/O.
*
* Since: 2.48
*/
/**
* GDtlsConnection:
*
* Abstract base class for the backend-specific #GDtlsClientConnection
* and #GDtlsServerConnection types.
* `GDtlsConnection` is the base DTLS connection class type, which wraps
* a [iface@Gio.DatagramBased] and provides DTLS encryption on top of it. Its
* subclasses, [iface@Gio.DtlsClientConnection] and
* [iface@Gio.DtlsServerConnection], implement client-side and server-side DTLS,
* respectively.
*
* For TLS support, see [class@Gio.TlsConnection].
*
* As DTLS is datagram based, `GDtlsConnection` implements
* [iface@Gio.DatagramBased], presenting a datagram-socket-like API for the
* encrypted connection. This operates over a base datagram connection, which is
* also a `GDatagramBased` ([property@Gio.DtlsConnection:base-socket]).
*
* To close a DTLS connection, use [method@Gio.DtlsConnection.close].
*
* Neither [iface@Gio.DtlsServerConnection] or [iface@Gio.DtlsClientConnection]
* set the peer address on their base [iface@Gio.DatagramBased] if it is a
* [class@Gio.Socket] — it is up to the caller to do that if they wish. If they
* do not, and [method@Gio.Socket.close] is called on the base socket, the
* `GDtlsConnection` will not raise a `G_IO_ERROR_NOT_CONNECTED` error on
* further I/O.
*
* Since: 2.48
*/
G_DEFINE_INTERFACE (GDtlsConnection, g_dtls_connection, G_TYPE_DATAGRAM_BASED)
enum {

9
gio/gdtlsserverconnection.c
View File

@ -31,16 +31,13 @@
#include "glibintl.h"
/**
* SECTION:gdtlsserverconnection
* @short_description: DTLS server-side connection
* @include: gio/gio.h
* GDtlsServerConnection:
*
* #GDtlsServerConnection is the server-side subclass of #GDtlsConnection,
* representing a server-side DTLS connection.
* `GDtlsServerConnection` is the server-side subclass of
* [iface@Gio.DtlsConnection], representing a server-side DTLS connection.
*
* Since: 2.48
*/
G_DEFINE_INTERFACE (GDtlsServerConnection, g_dtls_server_connection,
G_TYPE_DTLS_CONNECTION)

8
gio/gdtlsserverconnection.h
View File

@ -35,14 +35,6 @@ G_BEGIN_DECLS
#define G_IS_DTLS_SERVER_CONNECTION(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), G_TYPE_DTLS_SERVER_CONNECTION))
#define G_DTLS_SERVER_CONNECTION_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), G_TYPE_DTLS_SERVER_CONNECTION, GDtlsServerConnectionInterface))
/**
* GDtlsServerConnection:
*
* DTLS server-side connection. This is the server-side implementation
* of a #GDtlsConnection.
*
* Since: 2.48
*/
typedef struct _GDtlsServerConnectionInterface GDtlsServerConnectionInterface;
/**

9
gio/gemblem.c
View File

@ -31,14 +31,11 @@
/**
* SECTION:gemblem
* @short_description: An object for emblems
* @include: gio/gio.h
* @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
* GEmblem:
*
* #GEmblem is an implementation of #GIcon that supports
* `GEmblem` is an implementation of [iface@Gio.Icon] that supports
* having an emblem, which is an icon with additional properties.
* It can than be added to a #GEmblemedIcon.
* It can than be added to a [class@Gio.EmblemedIcon].
*
* Currently, only metainformation about the emblem's origin is
* supported. More may be added in the future.

5
gio/gemblem.h
View File

@ -37,11 +37,6 @@ G_BEGIN_DECLS
#define G_IS_EMBLEM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_EMBLEM))
#define G_EMBLEM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_EMBLEM, GEmblemClass))
/**
* GEmblem:
*
* An object for Emblems
*/
typedef struct _GEmblem GEmblem;
typedef struct _GEmblemClass GEmblemClass;

13
gio/gemblemedicon.c
View File

@ -33,17 +33,14 @@
/**
* SECTION:gemblemedicon
* @short_description: Icon with emblems
* @include: gio/gio.h
* @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
* GEmblemedIcon:
*
* #GEmblemedIcon is an implementation of #GIcon that supports
* `GEmblemedIcon` is an implementation of [iface@Gio.Icon] that supports
* adding an emblem to an icon. Adding multiple emblems to an
* icon is ensured via g_emblemed_icon_add_emblem().
* icon is ensured via [method@Gio.EmblemedIcon.add_emblem].
*
* Note that #GEmblemedIcon allows no control over the position
* of the emblems. See also #GEmblem for more information.
* Note that `GEmblemedIcon` allows no control over the position
* of the emblems. See also [class@Gio.Emblem] for more information.
**/
enum {

5
gio/gemblemedicon.h
View File

@ -40,11 +40,6 @@ G_BEGIN_DECLS
#define G_IS_EMBLEMED_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_EMBLEMED_ICON))
#define G_EMBLEMED_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_EMBLEMED_ICON, GEmblemedIconClass))
/**
* GEmblemedIcon:
*
* An implementation of #GIcon for icons with emblems.
**/
typedef struct _GEmblemedIcon GEmblemedIcon;
typedef struct _GEmblemedIconClass GEmblemedIconClass;
typedef struct _GEmblemedIconPrivate GEmblemedIconPrivate;

107
gio/gfileattribute.c
View File

@ -30,113 +30,6 @@
#include "glibintl.h"
/**
* SECTION:gfileattribute
* @short_description: Key-Value Paired File Attributes
* @include: gio/gio.h
* @see_also: #GFile, #GFileInfo
*
* File attributes in GIO consist of a list of key-value pairs.
*
* Keys are strings that contain a key namespace and a key name, separated
* by a colon, e.g. "namespace::keyname". Namespaces are included to sort
* key-value pairs by namespaces for relevance. Keys can be retrieved
* using wildcards, e.g. "standard::*" will return all of the keys in the
* "standard" namespace.
*
* The list of possible attributes for a filesystem (pointed to by a #GFile) is
* available as a #GFileAttributeInfoList. This list is queryable by key names
* as indicated earlier.
*
* Information is stored within the list in #GFileAttributeInfo structures.
* The info structure can store different types, listed in the enum
* #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
* be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
*
* Classes that implement #GFileIface will create a #GFileAttributeInfoList and
* install default keys and values for their given file system, architecture,
* and other possible implementation details (e.g., on a UNIX system, a file
* attribute key will be registered for the user id for a given file).
*
* ## Default Namespaces
*
* - `"standard"`: The "Standard" namespace. General file information that
* any application may need should be put in this namespace. Examples
* include the file's name, type, and size.
* - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key
* in this namespace is "value", which contains the value of the current
* entity tag.
* - `"id"`: The "Identification" namespace. This namespace is used by file
* managers and applications that list directories to check for loops and
* to uniquely identify files.
* - `"access"`: The "Access" namespace. Used to check if a user has the
* proper privileges to access files and perform file operations. Keys in
* this namespace are made to be generic and easily understood, e.g. the
* "can_read" key is %TRUE if the current user has permission to read the
* file. UNIX permissions and NTFS ACLs in Windows should be mapped to
* these values.
* - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys
* for checking if a file or path supports mount operations, e.g. mount,
* unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.
* - `"time"`: The "Time" namespace. Includes file access, changed, created
* times.
* - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and
* may not be available for all files. Examples include the UNIX "UID",
* "GID", etc.
* - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may
* not be available for all files. Examples include "is_system" for checking
* if a file is marked as a system file, and "is_archive" for checking if a
* file is marked as an archive file.
* - `"owner"`: The "Owner" namespace. Includes information about who owns a
* file. May not be available for all file systems. Examples include "user"
* for getting the user name of the file owner. This information is often
* mapped from some backend specific data such as a UNIX UID.
* - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file
* thumbnails and their location within the file system. Examples of keys in
* this namespace include "path" to get the location of a thumbnail, "failed"
* to check if thumbnailing of the file failed, and "is-valid" to check if
* the thumbnail is outdated.
* - `"filesystem"`: The "Filesystem" namespace. Gets information about the
* file system where a file is located, such as its type, how much space is
* left available, and the overall size of the file system.
* - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information
* about the current GVFS backend in use.
* - `"xattr"`: The "xattr" namespace. Gets information about extended
* user attributes. See attr(5). The "user." prefix of the extended user
* attribute name is stripped away when constructing keys in this namespace,
* e.g. "xattr::mime_type" for the extended attribute with the name
* "user.mime_type". Note that this information is only available if
* GLib has been built with extended attribute support.
* - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about
* extended attributes which are not user-specific. See attr(5). Note
* that this information is only available if GLib has been built with
* extended attribute support.
* - `"selinux"`: The "SELinux" namespace. Includes information about the
* SELinux context of files. Note that this information is only available
* if GLib has been built with SELinux support.
*
* Please note that these are not all of the possible namespaces.
* More namespaces can be added from GIO modules or by individual applications.
* For more information about writing GIO modules, see #GIOModule.
*
* <!-- TODO: Implementation note about using extended attributes on supported
* file systems -->
*
* ## Default Keys
*
* For a list of the built-in keys and their types, see the
* [GFileInfo][GFileInfo] documentation.
*
* Note that there are no predefined keys in the "xattr" and "xattr-sys"
* namespaces. Keys for the "xattr" namespace are constructed by stripping
* away the "user." prefix from the extended user attribute, and prepending
* "xattr::". Keys for the "xattr-sys" namespace are constructed by
* concatenating "xattr-sys::" with the extended attribute name. All extended
* attribute values are returned as hex-encoded strings in which bytes outside
* the ASCII range are encoded as escape sequences of the form \x`nn`
* where `nn` is a 2-digit hexadecimal number.
*/
/**
* _g_file_attribute_value_free:
* @attr: a #GFileAttributeValue.

10
gio/gfileicon.c
View File

@ -33,15 +33,13 @@
/**
* SECTION:gfileicon
* @short_description: Icons pointing to an image file
* @include: gio/gio.h
* @see_also: #GIcon, #GLoadableIcon
* GFileIcon:
*
* #GFileIcon specifies an icon by pointing to an image file
* `GFileIcon` specifies an icon by pointing to an image file
* to be used as icon.
*
**/
* It implements [iface@Gio.LoadableIcon].
*/
static void g_file_icon_icon_iface_init (GIconIface *iface);
static void g_file_icon_loadable_icon_iface_init (GLoadableIconIface *iface);

5
gio/gfileicon.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILE_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_ICON))
#define G_FILE_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_ICON, GFileIconClass))
/**
* GFileIcon:
*
* Gets an icon for a #GFile. Implements #GLoadableIcon.
**/
typedef struct _GFileIconClass GFileIconClass;
GIO_AVAILABLE_IN_ALL

45
gio/gfileinfo.c
View File

@ -21,45 +21,44 @@
*/
/**
* SECTION:gfileinfo
* @short_description: File Information and Attributes
* @include: gio/gio.h
* @see_also: #GFile, [GFileAttribute][gio-GFileAttribute]
* GFileInfo:
*
* Functionality for manipulating basic metadata for files. #GFileInfo
* Stores information about a file system object referenced by a [iface@Gio.File].
*
* Functionality for manipulating basic metadata for files. `GFileInfo`
* implements methods for getting information that all files should
* contain, and allows for manipulation of extended attributes.
*
* See [GFileAttribute][gio-GFileAttribute] for more information on how
* GIO handles file attributes.
* See [file-attributes.html](file attributes) for more information on how GIO
* handles file attributes.
*
* To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
* async variant). To obtain a #GFileInfo for a file input or output
* stream, use g_file_input_stream_query_info() or
* g_file_output_stream_query_info() (or their async variants).
* To obtain a `GFileInfo` for a [iface@Gio.File], use
* [method@Gio.File.query_info] (or its async variant). To obtain a `GFileInfo`
* for a file input or output stream, use [method@Gio.FileInputStream.query_info]
* or [method@Gio.FileOutputStream.query_info] (or their async variants).
*
* To change the actual attributes of a file, you should then set the
* attribute in the #GFileInfo and call g_file_set_attributes_from_info()
* or g_file_set_attributes_async() on a GFile.
* attribute in the `GFileInfo` and call [method@Gio.File.set_attributes_from_info]
* or [method@Gio.File.set_attributes_async] on a `GFile`.
*
* However, not all attributes can be changed in the file. For instance,
* the actual size of a file cannot be changed via g_file_info_set_size().
* You may call g_file_query_settable_attributes() and
* g_file_query_writable_namespaces() to discover the settable attributes
* the actual size of a file cannot be changed via [method@Gio.FileInfo.set_size].
* You may call [method@Gio.File.query_settable_attributes] and
* [method@Gio.File.query_writable_namespaces] to discover the settable attributes
* of a particular file at runtime.
*
* The direct accessors, such as g_file_info_get_name(), are slightly more
* The direct accessors, such as [method@Gio.FileInfo.get_name], are slightly more
* optimized than the generic attribute accessors, such as
* g_file_info_get_attribute_byte_string().This optimization will matter
* [method@Gio.FileInfo.get_attribute_byte_string].This optimization will matter
* only if calling the API in a tight loop.
*
* It is an error to call these accessors without specifying their required file
* attributes when creating the #GFileInfo. Use g_file_info_has_attribute() or
* g_file_info_list_attributes() to check what attributes are specified for a
* #GFileInfo.
* attributes when creating the `GFileInfo`. Use
* [method@Gio.FileInfo.has_attribute] or [method@Gio.FileInfo.list_attributes]
* to check what attributes are specified for a `GFileInfo`.
*
* #GFileAttributeMatcher allows for searching through a #GFileInfo for
* attributes.
* [struct@Gio.FileAttributeMatcher] allows for searching through a `GFileInfo`
* for attributes.
**/
#include "config.h"

5
gio/gfileinfo.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILE_INFO_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INFO))
#define G_FILE_INFO_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INFO, GFileInfoClass))
/**
* GFileInfo:
*
* Stores information about a file system object referenced by a #GFile.
**/
typedef struct _GFileInfoClass GFileInfoClass;

21
gio/gfilemonitor.c
View File

@ -31,23 +31,20 @@
#include "glibintl.h"
/**
* SECTION:gfilemonitor
* @short_description: File Monitor
* @include: gio/gio.h
* GFileMonitor:
*
* Monitors a file or directory for changes.
*
* To obtain a #GFileMonitor for a file or directory, use
* g_file_monitor(), g_file_monitor_file(), or
* g_file_monitor_directory().
* To obtain a `GFileMonitor` for a file or directory, use
* [method@Gio.File.monitor], [method@Gio.File.monitor_file], or
* [method@Gio.File.monitor_directory].
*
* To get informed about changes to the file or directory you are
* monitoring, connect to the #GFileMonitor::changed signal. The
* signal will be emitted in the
* [thread-default main context][g-main-context-push-thread-default]
* of the thread that the monitor was created in
* (though if the global default main context is blocked, this may
* cause notifications to be blocked even if the thread-default
* monitoring, connect to the [signal@Gio.FileMonitor::changed] signal. The
* signal will be emitted in the thread-default main context (see
* [method@GLib.MainContext.push_thread_default]) of the thread that the monitor
* was created in (though if the global default main context is blocked, this
* may cause notifications to be blocked even if the thread-default
* context is still running).
**/

5
gio/gfilemonitor.h
View File

@ -41,11 +41,6 @@ G_BEGIN_DECLS
typedef struct _GFileMonitorClass GFileMonitorClass;
typedef struct _GFileMonitorPrivate GFileMonitorPrivate;
/**
* GFileMonitor:
*
* Watches for changes to a file.
**/
struct _GFileMonitor
{
GObject parent_instance;

7
gio/gfilenamecompleter.c
View File

@ -32,15 +32,12 @@
/**
* SECTION:gfilenamecompleter
* @short_description: Filename Completer
* @include: gio/gio.h
* GFilenameCompleter:
*
* Completes partial file and directory names given a partial string by
* looking in the file system for clues. Can return a list of possible
* completion strings for widget implementations.
*
**/
*/
enum {
GOT_COMPLETION_DATA,

5
gio/gfilenamecompleter.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILENAME_COMPLETER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_FILENAME_COMPLETER))
#define G_IS_FILENAME_COMPLETER_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILENAME_COMPLETER))
/**
* GFilenameCompleter:
*
* Completes filenames based on files that exist within the file system.
**/
typedef struct _GFilenameCompleterClass GFilenameCompleterClass;
struct _GFilenameCompleterClass

41
gio/gicon.c
View File

@ -41,38 +41,37 @@
#define G_ICON_SERIALIZATION_MAGIC0 ". "
/**
* SECTION:gicon
* @short_description: Interface for icons
* @include: gio/gio.h
* GIcon:
*
* #GIcon is a very minimal interface for icons. It provides functions
* `GIcon` is a very minimal interface for icons. It provides functions
* for checking the equality of two icons, hashing of icons and
* serializing an icon to and from strings.
*
* #GIcon does not provide the actual pixmap for the icon as this is out
* of GIO's scope, however implementations of #GIcon may contain the name
* of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
* `GIcon` does not provide the actual pixmap for the icon as this is out
* of GIO's scope, however implementations of `GIcon` may contain the name
* of an icon (see [class@Gio.ThemedIcon]), or the path to an icon
* (see [iface@Gio.LoadableIcon]).
*
* To obtain a hash of a #GIcon, see g_icon_hash().
* To obtain a hash of a `GIcon`, see [method@Gio.Icon.hash].
*
* To check if two #GIcons are equal, see g_icon_equal().
* To check if two `GIcon`s are equal, see [method@Gio.Icon.equal].
*
* For serializing a #GIcon, use g_icon_serialize() and
* g_icon_deserialize().
* For serializing a `GIcon`, use [method@Gio.Icon.serialize] and
* [func@Gio.Icon.deserialize].
*
* If you want to consume #GIcon (for example, in a toolkit) you must
* If you want to consume `GIcon` (for example, in a toolkit) you must
* be prepared to handle at least the three following cases:
* #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make
* sense to have fast-paths for other cases (like handling #GdkPixbuf
* directly, for example) but all compliant #GIcon implementations
* outside of GIO must implement #GLoadableIcon.
* [iface@Gio.LoadableIcon], [class@Gio.ThemedIcon] and [class@Gio.EmblemedIcon].
* It may also make sense to have fast-paths for other cases (like handling
* [class@GdkPixbuf.Pixbuf] directly, for example) but all compliant `GIcon`
* implementations outside of GIO must implement [iface@Gio.LoadableIcon].
*
* If your application or library provides one or more #GIcon
* If your application or library provides one or more `GIcon`
* implementations you need to ensure that your new implementation also
* implements #GLoadableIcon. Additionally, you must provide an
* implementation of g_icon_serialize() that gives a result that is
* understood by g_icon_deserialize(), yielding one of the built-in icon
* types.
* implements [iface@Gio.LoadableIcon]. Additionally, you must provide an
* implementation of [method@Gio.Icon.serialize] that gives a result that is
* understood by [func@Gio.Icon.deserialize], yielding one of the built-in
* icon types.
**/
typedef GIconIface GIconInterface;

5
gio/gicon.h
View File

@ -36,11 +36,6 @@ G_BEGIN_DECLS
#define G_IS_ICON(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ICON))
#define G_ICON_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ICON, GIconIface))
/**
* GIcon:
*
* An abstract type that specifies an icon.
**/
typedef struct _GIconIface GIconIface;
/**

29
gio/ginitable.c
View File

@ -26,35 +26,34 @@
/**
* SECTION:ginitable
* @short_description: Failable object initialization interface
* @include: gio/gio.h
* @see_also: #GAsyncInitable
* GInitable:
*
* #GInitable is implemented by objects that can fail during
* `GInitable` is implemented by objects that can fail during
* initialization. If an object implements this interface then
* it must be initialized as the first thing after construction,
* either via g_initable_init() or g_async_initable_init_async()
* (the latter is only available if it also implements #GAsyncInitable).
* either via [method@Gio.Initable.init] or [method@Gio.AsyncInitable.init_async]
* (the latter is only available if it also implements [iface@Gio.AsyncInitable]).
*
* If the object is not initialized, or initialization returns with an
* error, then all operations on the object except g_object_ref() and
* g_object_unref() are considered to be invalid, and have undefined
* behaviour. They will often fail with g_critical() or g_warning(), but
* this must not be relied on.
* error, then all operations on the object except `g_object_ref()` and
* `g_object_unref()` are considered to be invalid, and have undefined
* behaviour. They will often fail with [func@GLib.critical] or
* [func@GLib.warning], but this must not be relied on.
*
* Users of objects implementing this are not intended to use
* the interface method directly, instead it will be used automatically
* in various ways. For C applications you generally just call
* g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
* This will call g_initable_init() under the cover, returning %NULL and
* setting a #GError on failure (at which point the instance is
* [func@Gio.Initable.new] directly, or indirectly via a `foo_thing_new()` wrapper.
* This will call [method@Gio.Initable.init] under the cover, returning `NULL`
* and setting a `GError` on failure (at which point the instance is
* unreferenced).
*
* For bindings in languages where the native constructor supports
* exceptions the binding could check for objects implementing %GInitable
* exceptions the binding could check for objects implementing `GInitable`
* during normal construction and automatically initialize them, throwing
* an exception on failure.
*
* Since: 2.22
*/
typedef GInitableIface GInitableInterface;

7
gio/ginitable.h
View File

@ -37,13 +37,6 @@ G_BEGIN_DECLS
#define G_INITABLE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_INITABLE, GInitableIface))
#define G_TYPE_IS_INITABLE(type) (g_type_is_a ((type), G_TYPE_INITABLE))
/**
* GInitable:
*
* Interface for initializable objects.
*
* Since: 2.22
**/
typedef struct _GInitableIface GInitableIface;
/**

63
gio/giostream.c
View File

@ -32,57 +32,56 @@
#include "gtask.h"
/**
* SECTION:giostream
* @short_description: Base class for implementing read/write streams
* @include: gio/gio.h
* @see_also: #GInputStream, #GOutputStream
* GIOStream:
*
* GIOStream represents an object that has both read and write streams.
* `GIOStream` represents an object that has both read and write streams.
* Generally the two streams act as separate input and output streams,
* but they share some common resources and state. For instance, for
* seekable streams, both streams may use the same position.
*
* Examples of #GIOStream objects are #GSocketConnection, which represents
* a two-way network connection; and #GFileIOStream, which represents a
* Examples of `GIOStream` objects are [class@Gio.SocketConnection], which represents
* a two-way network connection; and [class@Gio.FileIOStream], which represents a
* file handle opened in read-write mode.
*
* To do the actual reading and writing you need to get the substreams
* with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
* with [method@Gio.IOStream.get_input_stream] and
* [method@Gio.IOStream.get_output_stream].
*
* The #GIOStream object owns the input and the output streams, not the other
* way around, so keeping the substreams alive will not keep the #GIOStream
* object alive. If the #GIOStream object is freed it will be closed, thus
* The `GIOStream` object owns the input and the output streams, not the other
* way around, so keeping the substreams alive will not keep the `GIOStream`
* object alive. If the `GIOStream` object is freed it will be closed, thus
* closing the substreams, so even if the substreams stay alive they will
* always return %G_IO_ERROR_CLOSED for all operations.
* always return `G_IO_ERROR_CLOSED` for all operations.
*
* To close a stream use g_io_stream_close() which will close the common
* To close a stream use [method@Gio.IOStream.close] which will close the common
* stream object and also the individual substreams. You can also close
* the substreams themselves. In most cases this only marks the
* substream as closed, so further I/O on it fails but common state in the
* #GIOStream may still be open. However, some streams may support
* "half-closed" states where one direction of the stream is actually shut down.
* `GIOStream` may still be open. However, some streams may support
* ‘half-closed’ states where one direction of the stream is actually shut down.
*
* Operations on #GIOStreams cannot be started while another operation on the
* #GIOStream or its substreams is in progress. Specifically, an application can
* read from the #GInputStream and write to the #GOutputStream simultaneously
* (either in separate threads, or as asynchronous operations in the same
* thread), but an application cannot start any #GIOStream operation while there
* is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and
* an application can’t start any #GInputStream or #GOutputStream operation
* while there is a #GIOStream operation in progress.
* Operations on `GIOStream`s cannot be started while another operation on the
* `GIOStream` or its substreams is in progress. Specifically, an application can
* read from the [class@Gio.InputStream] and write to the
* [class@Gio.OutputStream] simultaneously (either in separate threads, or as
* asynchronous operations in the same thread), but an application cannot start
* any `GIOStream` operation while there is a `GIOStream`, `GInputStream` or
* `GOutputStream` operation in progress, and an application can’t start any
* `GInputStream` or `GOutputStream` operation while there is a `GIOStream`
* operation in progress.
*
* This is a product of individual stream operations being associated with a
* given #GMainContext (the thread-default context at the time the operation was
* started), rather than entire streams being associated with a single
* #GMainContext.
* given [type@GLib.MainContext] (the thread-default context at the time the
* operation was started), rather than entire streams being associated with a
* single `GMainContext`.
*
* GIO may run operations on #GIOStreams from other (worker) threads, and this
* GIO may run operations on `GIOStream`s from other (worker) threads, and this
* may be exposed to application code in the behaviour of wrapper streams, such
* as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs,
* application code may only run operations on the base (wrapped) stream when
* the wrapper stream is idle. Note that the semantics of such operations may
* not be well-defined due to the state the wrapper stream leaves the base
* stream in (though they are guaranteed not to crash).
* as [class@Gio.BufferedInputStream] or [class@Gio.TlsConnection]. With such
* wrapper APIs, application code may only run operations on the base (wrapped)
* stream when the wrapper stream is idle. Note that the semantics of such
* operations may not be well-defined due to the state the wrapper stream leaves
* the base stream in (though they are guaranteed not to crash).
*
* Since: 2.22
*/

5
gio/giostream.h
View File

@ -40,11 +40,6 @@ G_BEGIN_DECLS
typedef struct _GIOStreamPrivate GIOStreamPrivate;
typedef struct _GIOStreamClass GIOStreamClass;
/**
* GIOStream:
*
* Base class for read-write streams.
**/
struct _GIOStream
{
GObject parent_instance;

34
gio/gmemorymonitor.c
View File

@ -31,14 +31,12 @@
#include "gtask.h"
/**
* SECTION:gmemorymonitor
* @title: GMemoryMonitor
* @short_description: Memory usage monitor
* @include: gio/gio.h
* GMemoryMonitor:
*
* #GMemoryMonitor will monitor system memory and suggest to the application
* `GMemoryMonitor` will monitor system memory and suggest to the application
* when to free memory so as to leave more room for other applications.
* It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/)
* It is implemented on Linux using the
* [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/)
* ([API documentation](https://hadess.pages.freedesktop.org/low-memory-monitor/)).
*
* There is also an implementation for use inside Flatpak sandboxes.
@ -46,11 +44,11 @@
* 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
* - 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
* - Call [`malloc_trim(3)`](man:malloc_trim(3)) 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
@ -58,9 +56,10 @@
* make future heap allocations slower (due to releasing cached heap pages back
* to the kernel).
*
* See #GMemoryMonitorWarningLevel for details on the various warning levels.
* See [type@Gio.MemoryMonitorWarningLevel] for details on the various warning
* levels.
*
* |[<!-- language="C" -->
* ```c
* static void
* warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level)
* {
@ -78,19 +77,10 @@
* G_CALLBACK (warning_cb), NULL);
* return m;
* }
* ]|
* ```
*
* Don't forget to disconnect the #GMemoryMonitor::low-memory-warning
* signal, and unref the #GMemoryMonitor itself when exiting.
*
* Since: 2.64
*/
/**
* GMemoryMonitor:
*
* #GMemoryMonitor monitors system memory and indicates when
* the system is low on memory.
* Don’t forget to disconnect the [signal@Gio.MemoryMonitor::low-memory-warning]
* signal, and unref the `GMemoryMonitor` itself when exiting.
*
* Since: 2.64
*/

81
gio/gmenumodel.c
View File

@ -27,13 +27,9 @@
#include "gmarshal-internal.h"
/**
* SECTION:gmenumodel
* @title: GMenuModel
* @short_description: An abstract class representing the contents of a menu
* @include: gio/gio.h
* @see_also: #GActionGroup
* GMenuModel:
*
* #GMenuModel represents the contents of a menu -- an ordered list of
* `GMenuModel` represents the contents of a menu — an ordered list of
* menu items. The items are associated with actions, which can be
* activated through them. Items can be grouped in sections, and may
* have submenus associated with them. Both items and sections usually
@ -41,20 +37,20 @@
* the associated action (ie whether it is stateful, and what kind of
* state it has) can influence the representation of the item.
*
* The conceptual model of menus in #GMenuModel is hierarchical:
* sections and submenus are again represented by #GMenuModels.
* The conceptual model of menus in `GMenuModel` is hierarchical:
* sections and submenus are again represented by `GMenuModel`s.
* Menus themselves do not define their own roles. Rather, the role
* of a particular #GMenuModel is defined by the item that references
* it (or, in the case of the 'root' menu, is defined by the context
* of a particular `GMenuModel` is defined by the item that references
* it (or, in the case of the ‘root’ menu, is defined by the context
* in which it is used).
*
* As an example, consider the visible portions of this menu:
*
* ## An example menu # {#menu-example}
* ## An example menu
*
* ![](menu-example.png)
*
* There are 8 "menus" visible in the screenshot: one menubar, two
* There are 8 ‘menus’ visible in the screenshot: one menubar, two
* submenus and 5 sections:
*
* - the toplevel menubar (containing 4 items)
@ -66,17 +62,17 @@
* - the Sources section (containing 2 items)
* - the Markup section (containing 2 items)
*
* The [example][menu-model] illustrates the conceptual connection between
* The [example](#a-menu-example) illustrates the conceptual connection between
* these 8 menus. Each large block in the figure represents a menu and the
* smaller blocks within the large block represent items in that menu. Some
* items contain references to other menus.
*
* ## A menu example # {#menu-model}
* ## A menu example
*
* ![](menu-model.png)
*
* Notice that the separators visible in the [example][menu-example]
* appear nowhere in the [menu model][menu-model]. This is because
* Notice that the separators visible in the [example](#an-example-menu)
* appear nowhere in the [menu model](#a-menu-example). This is because
* separators are not explicitly represented in the menu model. Instead,
* a separator is inserted between any two non-empty sections of a menu.
* Section items can have labels just like any other item. In that case,
@ -85,32 +81,32 @@
* The motivation for this abstract model of application controls is
* that modern user interfaces tend to make these controls available
* outside the application. Examples include global menus, jumplists,
* dash boards, etc. To support such uses, it is necessary to 'export'
* dash boards, etc. To support such uses, it is necessary to ‘export’
* information about actions and their representation in menus, which
* is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
* and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
* #GActionGroup and #GMenuModel. The client-side counterparts to
* make use of the exported information are #GDBusActionGroup and
* #GDBusMenuModel.
* is exactly what the action group exporter and the menu model exporter do for
* [iface@Gio.ActionGroup] and [class@Gio.MenuModel]. The client-side
* counterparts to make use of the exported information are
* [class@Gio.DBusActionGroup] and [class@Gio.DBusMenuModel].
*
* The API of #GMenuModel is very generic, with iterators for the
* attributes and links of an item, see g_menu_model_iterate_item_attributes()
* and g_menu_model_iterate_item_links(). The 'standard' attributes and
* link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
* %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
* and %G_MENU_LINK_SUBMENU.
* The API of `GMenuModel` is very generic, with iterators for the
* attributes and links of an item, see
* [method@Gio.MenuModel.iterate_item_attributes] and
* [method@Gio.MenuModel.iterate_item_links]. The ‘standard’ attributes and
* link types have predefined names: `G_MENU_ATTRIBUTE_LABEL`,
* `G_MENU_ATTRIBUTE_ACTION`, `G_MENU_ATTRIBUTE_TARGET`, `G_MENU_LINK_SECTION`
* and `G_MENU_LINK_SUBMENU`.
*
* Items in a #GMenuModel represent active controls if they refer to
* Items in a `GMenuModel` represent active controls if they refer to
* an action that can get activated when the user interacts with the
* menu item. The reference to the action is encoded by the string id
* in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
* menu item. The reference to the action is encoded by the string ID
* in the `G_MENU_ATTRIBUTE_ACTION` attribute. An action ID uniquely
* identifies an action in an action group. Which action group(s) provide
* actions depends on the context in which the menu model is used.
* E.g. when the model is exported as the application menu of a
* #GtkApplication, actions can be application-wide or window-specific
* [class@Gtk.Application], actions can be application-wide or window-specific
* (and thus come from two different action groups). By convention, the
* application-wide actions have names that start with "app.", while the
* names of window-specific actions start with "win.".
* application-wide actions have names that start with `app.`, while the
* names of window-specific actions start with `win.`.
*
* While a wide variety of stateful actions is possible, the following
* is the minimum that is expected to be supported by all users of exported
@ -119,7 +115,7 @@
* - an action with no parameter type and boolean state
* - an action with string parameter type and string state
*
* ## Stateless
* ## Stateless
*
* A stateless action typically corresponds to an ordinary menu item.
*
@ -127,12 +123,12 @@
*
* ## Boolean State
*
* An action with a boolean state will most typically be used with a "toggle"
* or "switch" menu item. The state can be set directly, but activating the
* An action with a boolean state will most typically be used with a ‘toggle’
* or ‘switch’ menu item. The state can be set directly, but activating the
* action (with no parameter) results in the state being toggled.
*
* Selecting a toggle menu item will activate the action. The menu item should
* be rendered as "checked" when the state is true.
* be rendered as ‘checked’ when the state is true.
*
* ## String Parameter and State
*
@ -144,15 +140,8 @@
* Radio menu items, in addition to being associated with the action, will
* have a target value. Selecting that menu item will result in activation
* of the action with the target value as the parameter. The menu item should
* be rendered as "selected" when the state of the action is equal to the
* be rendered as ‘selected’ when the state of the action is equal to the
* target value of the menu item.
*/
/**
* GMenuModel:
*
* #GMenuModel is an opaque structure type. You must access it using the
* functions below.
*
* Since: 2.32
*/

37
gio/gmount.c
View File

@ -37,30 +37,29 @@
/**
* SECTION:gmount
* @short_description: Mount management
* @include: gio/gio.h
* @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
* GMount:
*
* The #GMount interface represents user-visible mounts. Note, when
* porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
* The `GMount` interface represents user-visible mounts. Note, when
* [porting from GnomeVFS](migrating-gnome-vfs.html), `GMount` is the moral
* equivalent of `GnomeVFSVolume`.
*
* #GMount is a "mounted" filesystem that you can access. Mounted is in
* quotes because it's not the same as a unix mount, it might be a gvfs
* `GMount` is a ‘mounted’ filesystem that you can access. Mounted is in
* quotes because it’s not the same as a UNIX mount, it might be a GVFS
* mount, but you can still access the files on it if you use GIO. Might or
* might not be related to a volume object.
*
* Unmounting a #GMount instance is an asynchronous operation. For
* more information about asynchronous operations, see #GAsyncResult
* and #GTask. To unmount a #GMount instance, first call
* g_mount_unmount_with_operation() with (at least) the #GMount instance and a
* #GAsyncReadyCallback. The callback will be fired when the
* operation has resolved (either with success or failure), and a
* #GAsyncResult structure will be passed to the callback. That
* callback should then call g_mount_unmount_with_operation_finish() with the #GMount
* and the #GAsyncResult data to see if the operation was completed
* successfully. If an @error is present when g_mount_unmount_with_operation_finish()
* is called, then it will be filled with any error information.
* Unmounting a `GMount` instance is an asynchronous operation. For
* more information about asynchronous operations, see [iface@Gio.AsyncResult]
* and [class@Gio.Task]. To unmount a `GMount` instance, first call
* [method@Gio.Mount.unmount_with_operation] with (at least) the `GMount`
* instance and a [type@Gio.AsyncReadyCallback]. The callback will be fired
* when the operation has resolved (either with success or failure), and a
* [struct@Gio.AsyncResult] structure will be passed to the callback. That
* callback should then call [method@Gio.Mount.unmount_with_operation_finish]
* with the `GMount` and the [struct@Gio.AsyncResult] data to see if the
* operation was completed successfully. If an `error` is present when
* [method@Gio.Mount.unmount_with_operation_finish] is called, then it will be
* filled with any error information.
**/
typedef GMountIface GMountInterface;

15
gio/gnetworkaddress.c
View File

@ -46,11 +46,9 @@
#define HAPPY_EYEBALLS_RESOLUTION_DELAY_MS 50
/**
* SECTION:gnetworkaddress
* @short_description: A GSocketConnectable for resolving hostnames
* @include: gio/gio.h
* GNetworkAddress:
*
* #GNetworkAddress provides an easy way to resolve a hostname and
* `GNetworkAddress` provides an easy way to resolve a hostname and
* then attempt to connect to that host, handling the possibility of
* multiple IP addresses and multiple address families.
*
@ -58,17 +56,10 @@
* as this object is kept alive which may have unexpected results if
* alive for too long.
*
* See #GSocketConnectable for an example of using the connectable
* See [iface@Gio.SocketConnectable] for an example of using the connectable
* interface.
*/
/**
* GNetworkAddress:
*
* A #GSocketConnectable for resolving a hostname and connecting to
* that host.
*/
struct _GNetworkAddressPrivate {
gchar *hostname;
guint16 port;

12
gobject/gvaluecollector.h
View File

@ -18,17 +18,7 @@
*
* gvaluecollector.h: GValue varargs stubs
*/
/**
* SECTION:value_collection
* @Short_description: Converting varargs to generic values
* @Title: Varargs Value Collection
*
* 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.
*/
#ifndef __G_VALUE_COLLECTOR_H__
#define __G_VALUE_COLLECTOR_H__