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

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

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

See merge request GNOME/glib!3667
This commit is contained in:
Philip Withnall 2023-10-25 14:28:43 +00:00
commit 58cce38f37
37 changed files with 344 additions and 510 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
gio/gdbusmethodinvocation.c
View File

@ -40,17 +40,18 @@
#include "glibintl.h"
/**
* SECTION:gdbusmethodinvocation
* @short_description: Object for handling remote calls
* @include: gio/gio.h
* GDBusMethodInvocation:
*
* Instances of the #GDBusMethodInvocation class are used when
* Instances of the `GDBusMethodInvocation` class are used when
* handling D-Bus method calls. It provides a way to asynchronously
* return results and errors.
*
* The normal way to obtain a #GDBusMethodInvocation object is to receive
* it as an argument to the handle_method_call() function in a
* #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
* The normal way to obtain a `GDBusMethodInvocation` object is to receive
* it as an argument to the `handle_method_call()` function in a
* [type@Gio.DBusInterfaceVTable] that was passed to
* [method@Gio.DBusConnection.register_object].
*
* Since: 2.26
*/
typedef struct _GDBusMethodInvocationClass GDBusMethodInvocationClass;
@ -68,14 +69,6 @@ struct _GDBusMethodInvocationClass
GObjectClass parent_class;
};
/**
* GDBusMethodInvocation:
*
* The #GDBusMethodInvocation structure contains only private data and
* should only be accessed using the provided API.
*
* Since: 2.26
*/
struct _GDBusMethodInvocation
{
/*< private >*/

111
gio/gdbusobjectmanagerclient.c
View File

@ -43,85 +43,88 @@
#include "gmarshal-internal.h"
/**
* SECTION:gdbusobjectmanagerclient
* @short_description: Client-side object manager
* @include: gio/gio.h
* GDBusObjectManagerClient:
*
* #GDBusObjectManagerClient is used to create, monitor and delete object
* proxies for remote objects exported by a #GDBusObjectManagerServer (or any
* code implementing the
* `GDBusObjectManagerClient` is used to create, monitor and delete object
* proxies for remote objects exported by a [class@Gio.DBusObjectManagerServer]
* (or any code implementing the
* [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
* interface).
*
* Once an instance of this type has been created, you can connect to
* the #GDBusObjectManager::object-added and
* #GDBusObjectManager::object-removed signals and inspect the
* #GDBusObjectProxy objects returned by
* g_dbus_object_manager_get_objects().
* the [signal@Gio.DBusObjectManager::object-added] and
* [signal@Gio.DBusObjectManager::object-removed signals] and inspect the
* [class@Gio.DBusObjectProxy] objects returned by
* [method@Gio.DBusObjectManager.get_objects].
*
* If the name for a #GDBusObjectManagerClient is not owned by anyone at
* If the name for a `GDBusObjectManagerClient` is not owned by anyone at
* object construction time, the default behavior is to request the
* message bus to launch an owner for the name. This behavior can be
* disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
* flag. It's also worth noting that this only works if the name of
* disabled using the `G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START`
* flag. It’s also worth noting that this only works if the name of
* interest is activatable in the first place. E.g. in some cases it
* is not possible to launch an owner for the requested name. In this
* case, #GDBusObjectManagerClient object construction still succeeds but
* case, `GDBusObjectManagerClient` object construction still succeeds but
* there will be no object proxies
* (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
* the #GDBusObjectManagerClient:name-owner property is %NULL.
* (e.g. [method@Gio.DBusObjectManager.get_objects] returns the empty list) and
* the [property@Gio.DBusObjectManagerClient:name-owner] property is `NULL`.
*
* The owner of the requested name can come and go (for example
* consider a system service being restarted) – #GDBusObjectManagerClient
* handles this case too; simply connect to the #GObject::notify
* signal to watch for changes on the #GDBusObjectManagerClient:name-owner
* property. When the name owner vanishes, the behavior is that
* #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
* emission of the #GObject::notify signal) and then
* #GDBusObjectManager::object-removed signals are synthesized
* consider a system service being restarted) – `GDBusObjectManagerClient`
* handles this case too; simply connect to the [signal@GObject.Object::notify]
* signal to watch for changes on the
* [property@Gio.DBusObjectManagerClient:name-owner] property. When the name
* owner vanishes, the behavior is that
* [property@Gio.DBusObjectManagerClient:name-owner] is set to `NULL` (this
* includes emission of the [signal@GObject.Object::notify] signal) and then
* [signal@Gio.DBusObjectManager::object-removed] signals are synthesized
* for all currently existing object proxies. Since
* #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
* use this information to disambiguate a synthesized signal from a
* genuine signal caused by object removal on the remote
* #GDBusObjectManager. Similarly, when a new name owner appears,
* #GDBusObjectManager::object-added signals are synthesized
* while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
* object proxies have been added, the #GDBusObjectManagerClient:name-owner
* is set to the new name owner (this includes emission of the
* #GObject::notify signal). Furthermore, you are guaranteed that
* #GDBusObjectManagerClient:name-owner will alternate between a name owner
* (e.g. `:1.42`) and %NULL even in the case where
* [property@Gio.DBusObjectManagerClient:name-owner] is `NULL` when this
* happens, you can use this information to disambiguate a synthesized signal
* from a genuine signal caused by object removal on the remote
* [iface@Gio.DBusObjectManager]. Similarly, when a new name owner appears,
* [signal@Gio.DBusObjectManager::object-added] signals are synthesized
* while [property@Gio.DBusObjectManagerClient:name-owner] is still `NULL`. Only
* when all object proxies have been added, the
* [property@Gio.DBusObjectManagerClient:name-owner] is set to the new name
* owner (this includes emission of the [signal@GObject.Object::notify] signal).
* Furthermore, you are guaranteed that
* [property@Gio.DBusObjectManagerClient:name-owner] will alternate between a
* name owner (e.g. `:1.42`) and `NULL` even in the case where
* the name of interest is atomically replaced
*
* Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
* instances. All signals (including the
* org.freedesktop.DBus.Properties::PropertiesChanged signal)
* delivered to #GDBusProxy instances are guaranteed to originate
* Ultimately, `GDBusObjectManagerClient` is used to obtain
* [class@Gio.DBusProxy] instances. All signals (including the
* `org.freedesktop.DBus.Properties::PropertiesChanged` signal)
* delivered to [class@Gio.DBusProxy] instances are guaranteed to originate
* from the name owner. This guarantee along with the behavior
* described above, means that certain race conditions including the
* "half the proxy is from the old owner and the other half is from
* the new owner" problem cannot happen.
* “half the proxy is from the old owner and the other half is from
* the new owner” problem cannot happen.
*
* To avoid having the application connect to signals on the returned
* #GDBusObjectProxy and #GDBusProxy objects, the
* #GDBusObject::interface-added,
* #GDBusObject::interface-removed,
* #GDBusProxy::g-properties-changed and
* #GDBusProxy::g-signal signals
* are also emitted on the #GDBusObjectManagerClient instance managing these
* [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects, the
* [signal@Gio.DBusObject::interface-added],
* [signal@Gio.DBusObject::interface-removed],
* [signal@Gio.DBusProxy::g-properties-changed] and
* [signal@Gio.DBusProxy::g-signal] signals
* are also emitted on the `GDBusObjectManagerClient` instance managing these
* objects. The signals emitted are
* #GDBusObjectManager::interface-added,
* #GDBusObjectManager::interface-removed,
* #GDBusObjectManagerClient::interface-proxy-properties-changed and
* #GDBusObjectManagerClient::interface-proxy-signal.
* [signal@Gio.DBusObjectManager::interface-added],
* [signal@Gio.DBusObjectManager::interface-removed],
* [signal@Gio.DBusObjectManagerClient::interface-proxy-properties-changed] and
* [signal@Gio.DBusObjectManagerClient::interface-proxy-signal].
*
* Note that all callbacks and signals are emitted in the
* [thread-default main context][g-main-context-push-thread-default]
* that the #GDBusObjectManagerClient object was constructed
* in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
* originating from the #GDBusObjectManagerClient object will be created in
* thread-default main context (see
* [method@GLib.MainContext.push_thread_default]) that the
* `GDBusObjectManagerClient` object was constructed in. Additionally, the
* [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects
* originating from the `GDBusObjectManagerClient` object will be created in
* the same context and, consequently, will deliver signals in the
* same main loop.
*
* Since: 2.30
*/
struct _GDBusObjectManagerClientPrivate

8
gio/gdbusobjectmanagerclient.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusObjectManagerClientClass GDBusObjectManagerClientClass;
typedef struct _GDBusObjectManagerClientPrivate GDBusObjectManagerClientPrivate;
/**
* GDBusObjectManagerClient:
*
* The #GDBusObjectManagerClient structure contains private data and should
* only be accessed using the provided API.
*
* Since: 2.30
*/
struct _GDBusObjectManagerClient
{
/*< private >*/

10
gio/gdbusobjectproxy.c
View File

@ -32,13 +32,11 @@
#include "glibintl.h"
/**
* SECTION:gdbusobjectproxy
* @short_description: Client-side D-Bus object
* @include: gio/gio.h
* GDBusObjectProxy:
*
* A #GDBusObjectProxy is an object used to represent a remote object
* with one or more D-Bus interfaces. Normally, you don't instantiate
* a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
* A `GDBusObjectProxy` is an object used to represent a remote object
* with one or more D-Bus interfaces. Normally, you don’t instantiate
* a `GDBusObjectProxy` yourself — typically [class@Gio.DBusObjectManagerClient]
* is used to obtain it.
*
* Since: 2.30

8
gio/gdbusobjectproxy.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusObjectProxyClass GDBusObjectProxyClass;
typedef struct _GDBusObjectProxyPrivate GDBusObjectProxyPrivate;
/**
* GDBusObjectProxy:
*
* The #GDBusObjectProxy structure contains private data and should
* only be accessed using the provided API.
*
* Since: 2.30
*/
struct _GDBusObjectProxy
{
/*< private >*/

12
gio/gdesktopappinfo.c
View File

@ -63,12 +63,9 @@
#endif
/**
* SECTION:gdesktopappinfo
* @title: GDesktopAppInfo
* @short_description: Application information from desktop files
* @include: gio/gdesktopappinfo.h
* GDesktopAppInfo:
*
* #GDesktopAppInfo is an implementation of #GAppInfo based on
* `GDesktopAppInfo` is an implementation of [iface@Gio.AppInfo] based on
* desktop files.
*
* Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
@ -95,11 +92,6 @@ static gboolean g_desktop_app_info_ensure_saved (GDesktopAppInfo *info,
GError **error);
static gboolean g_desktop_app_info_load_file (GDesktopAppInfo *self);
/**
* GDesktopAppInfo:
*
* Information about an installed application from a desktop file.
*/
struct _GDesktopAppInfo
{
GObject parent_instance;

15
gio/gfileinputstream.c
View File

@ -33,20 +33,17 @@
/**
* SECTION:gfileinputstream
* @short_description: File input streaming operations
* @include: gio/gio.h
* @see_also: #GInputStream, #GDataInputStream, #GSeekable
* GFileInputStream:
*
* GFileInputStream provides input streams that take their
* `GFileInputStream` provides input streams that take their
* content from a file.
*
* GFileInputStream implements #GSeekable, which allows the input
* `GFileInputStream` implements [iface@Gio.Seekable], which allows the input
* stream to jump to arbitrary positions in the file, provided the
* filesystem of the file allows it. To find the position of a file
* input stream, use g_seekable_tell(). To find out if a file input
* stream supports seeking, use g_seekable_can_seek().
* To position a file input stream, use g_seekable_seek().
* input stream, use [method@Gio.Seekable.tell]. To find out if a file input
* stream supports seeking, use [iface@Gio.Seekable.can_seek].
* To position a file input stream, use [iface@Gio.Seekable.seek].
**/
static void g_file_input_stream_seekable_iface_init (GSeekableIface *iface);

8
gio/gfileinputstream.h
View File

@ -38,14 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILE_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INPUT_STREAM))
#define G_FILE_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INPUT_STREAM, GFileInputStreamClass))
/**
* GFileInputStream:
*
* A subclass of GInputStream for opened files. This adds
* a few file-specific operations and seeking.
*
* #GFileInputStream implements #GSeekable.
**/
typedef struct _GFileInputStreamClass GFileInputStreamClass;
typedef struct _GFileInputStreamPrivate GFileInputStreamPrivate;

19
gio/gfileoutputstream.c
View File

@ -33,25 +33,22 @@
/**
* SECTION:gfileoutputstream
* @short_description: File output streaming operations
* @include: gio/gio.h
* @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
* GFileOutputStream:
*
* GFileOutputStream provides output streams that write their
* `GFileOutputStream` provides output streams that write their
* content to a file.
*
* GFileOutputStream implements #GSeekable, which allows the output
* `GFileOutputStream` implements [iface@Gio.Seekable], which allows the output
* stream to jump to arbitrary positions in the file and to truncate
* the file, provided the filesystem of the file supports these
* operations.
*
* To find the position of a file output stream, use g_seekable_tell().
* To find the position of a file output stream, use [method@Gio.Seekable.tell].
* To find out if a file output stream supports seeking, use
* g_seekable_can_seek().To position a file output stream, use
* g_seekable_seek(). To find out if a file output stream supports
* truncating, use g_seekable_can_truncate(). To truncate a file output
* stream, use g_seekable_truncate().
* [method@Gio.Seekable.can_seek].To position a file output stream, use
* [method@Gio.Seekable.seek]. To find out if a file output stream supports
* truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file output
* stream, use [method@Gio.Seekable.truncate].
**/
static void g_file_output_stream_seekable_iface_init (GSeekableIface *iface);

8
gio/gfileoutputstream.h
View File

@ -38,14 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILE_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_OUTPUT_STREAM))
#define G_FILE_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_OUTPUT_STREAM, GFileOutputStreamClass))
/**
* GFileOutputStream:
*
* A subclass of GOutputStream for opened files. This adds
* a few file-specific operations and seeking and truncating.
*
* #GFileOutputStream implements GSeekable.
**/
typedef struct _GFileOutputStreamClass GFileOutputStreamClass;
typedef struct _GFileOutputStreamPrivate GFileOutputStreamPrivate;

4
gio/gfilterinputstream.c
View File

@ -27,9 +27,7 @@
/**
* SECTION:gfilterinputstream
* @short_description: Filter Input Stream
* @include: gio/gio.h
* GFilterInputStream:
*
* Base class for input stream implementations that perform some
* kind of filtering operation on a base stream. Typical examples

5
gio/gfilterinputstream.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILTER_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_INPUT_STREAM))
#define G_FILTER_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_INPUT_STREAM, GFilterInputStreamClass))
/**
* GFilterInputStream:
*
* A base class for all input streams that work on an underlying stream.
**/
typedef struct _GFilterInputStreamClass GFilterInputStreamClass;
struct _GFilterInputStream

4
gio/gfilteroutputstream.c
View File

@ -27,9 +27,7 @@
/**
* SECTION:gfilteroutputstream
* @short_description: Filter Output Stream
* @include: gio/gio.h
* GFilterOutputStream:
*
* Base class for output stream implementations that perform some
* kind of filtering operation on a base stream. Typical examples

5
gio/gfilteroutputstream.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILTER_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_OUTPUT_STREAM))
#define G_FILTER_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_OUTPUT_STREAM, GFilterOutputStreamClass))
/**
* GFilterOutputStream:
*
* A base class for all output streams that work on an underlying stream.
**/
typedef struct _GFilterOutputStreamClass GFilterOutputStreamClass;
struct _GFilterOutputStream

17
gio/gnetworkservice.c
View File

@ -43,28 +43,19 @@
/**
* SECTION:gnetworkservice
* @short_description: A GSocketConnectable for resolving SRV records
* @include: gio/gio.h
* GNetworkService:
*
* Like #GNetworkAddress does with hostnames, #GNetworkService
* Like [class@Gio.NetworkAddress] does with hostnames, `GNetworkService`
* provides an easy way to resolve a SRV record, and then attempt to
* connect to one of the hosts that implements that service, handling
* service priority/weighting, multiple IP addresses, and multiple
* address families.
*
* See #GSrvTarget for more information about SRV records, and see
* #GSocketConnectable for an example of using the connectable
* See [struct@Gio.SrvTarget] for more information about SRV records, and see
* [iface@Gio.SocketConnectable] for an example of using the connectable
* interface.
*/
/**
* GNetworkService:
*
* A #GSocketConnectable for resolving a SRV record and connecting to
* that service.
*/
struct _GNetworkServicePrivate
{
gchar *service, *protocol, *domain, *scheme;

12
gio/gproxy.c
View File

@ -29,16 +29,14 @@
#include "glibintl.h"
/**
* SECTION:gproxy
* @short_description: Interface for proxy handling
* @include: gio/gio.h
* GProxy:
*
* A #GProxy handles connecting to a remote host via a given type of
* proxy server. It is implemented by the 'gio-proxy' extension point.
* A `GProxy` handles connecting to a remote host via a given type of
* proxy server. It is implemented by the `gio-proxy` extension point.
* The extensions are named after their proxy protocol name. As an
* example, a SOCKS5 proxy implementation can be retrieved with the
* name 'socks5' using the function
* g_io_extension_point_get_extension_by_name().
* name `socks5` using the function
* [method@Gio.IOExtensionPoint.get_extension_by_name].
*
* Since: 2.26
**/

7
gio/gproxy.h
View File

@ -48,13 +48,6 @@ G_BEGIN_DECLS
*/
#define G_PROXY_EXTENSION_POINT_NAME "gio-proxy"
/**
* GProxy:
*
* Interface that handles proxy connection and payload.
*
* Since: 2.26
*/
typedef struct _GProxyInterface GProxyInterface;
/**

19
gio/gproxyaddressenumerator.c
View File

@ -42,19 +42,18 @@
#include "gsocketconnectable.h"
/**
* SECTION:gproxyaddressenumerator
* @short_description: Proxy wrapper enumerator for socket addresses
* @include: gio/gio.h
* GProxyAddressEnumerator:
*
* #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which
* takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator
* and wraps them in #GProxyAddress instances, using the given
* #GProxyAddressEnumerator:proxy-resolver.
* `GProxyAddressEnumerator` is a wrapper around
* [class@Gio.SocketAddressEnumerator] which takes the [class@Gio.SocketAddress]
* instances returned by the [class@Gio.SocketAddressEnumerator]
* and wraps them in [class@Gio.ProxyAddress] instances, using the given
* [property@Gio.ProxyAddressEnumerator:proxy-resolver].
*
* This enumerator will be returned (for example, by
* g_socket_connectable_enumerate()) as appropriate when a proxy is configured;
* there should be no need to manually wrap a #GSocketAddressEnumerator instance
* with one.
* [method@Gio.SocketConnectable.enumerate]) as appropriate when a proxy is
* configured; there should be no need to manually wrap a
* [class@Gio.SocketAddressEnumerator] instance with one.
*/
#define GET_PRIVATE(o) (G_PROXY_ADDRESS_ENUMERATOR (o)->priv)

8
gio/gproxyaddressenumerator.h
View File

@ -38,14 +38,6 @@ G_BEGIN_DECLS
#define G_IS_PROXY_ADDRESS_ENUMERATOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_PROXY_ADDRESS_ENUMERATOR))
#define G_PROXY_ADDRESS_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_PROXY_ADDRESS_ENUMERATOR, GProxyAddressEnumeratorClass))
/**
* GProxyAddressEnumerator:
*
* A subclass of #GSocketAddressEnumerator that takes another address
* enumerator and wraps each of its results in a #GProxyAddress as
* directed by the default #GProxyResolver.
*/
typedef struct _GProxyAddressEnumeratorClass GProxyAddressEnumeratorClass;
typedef struct _GProxyAddressEnumeratorPrivate GProxyAddressEnumeratorPrivate;

17
gio/gproxyresolver.c
View File

@ -36,17 +36,16 @@
#include "gnetworkingprivate.h"
/**
* SECTION:gproxyresolver
* @short_description: Asynchronous and cancellable network proxy resolver
* @include: gio/gio.h
* GProxyResolver:
*
* #GProxyResolver provides synchronous and asynchronous network proxy
* resolution. #GProxyResolver is used within #GSocketClient through
* the method g_socket_connectable_proxy_enumerate().
* `GProxyResolver` provides synchronous and asynchronous network proxy
* resolution. `GProxyResolver` is used within [class@Gio.SocketClient] through
* the method [method@Gio.SocketConnectable.proxy_enumerate].
*
* Implementations of #GProxyResolver based on libproxy and GNOME settings can
* be found in glib-networking. GIO comes with an implementation for use inside
* Flatpak portals.
* Implementations of `GProxyResolver` based on
* [libproxy](https://github.com/libproxy/libproxy) and GNOME settings can be
* found in [glib-networking](https://gitlab.gnome.org/GNOME/glib-networking).
* GIO comes with an implementation for use inside Flatpak portals.
*/
/**

40
gio/gresolver.c
View File

@ -43,22 +43,27 @@
/**
* SECTION:gresolver
* @short_description: Asynchronous and cancellable DNS resolver
* @include: gio/gio.h
* GResolver:
*
* #GResolver provides cancellable synchronous and asynchronous DNS
* resolution, for hostnames (g_resolver_lookup_by_address(),
* g_resolver_lookup_by_name() and their async variants) and SRV
* (service) records (g_resolver_lookup_service()).
* The object that handles DNS resolution. Use [func@Gio.Resolver.get_default]
* to get the default resolver.
*
* #GNetworkAddress and #GNetworkService provide wrappers around
* #GResolver functionality that also implement #GSocketConnectable,
* making it easy to connect to a remote host/service.
* `GResolver` provides cancellable synchronous and asynchronous DNS
* resolution, for hostnames ([method@Gio.Resolver.lookup_by_address],
* [method@Gio.Resolver.lookup_by_name] and their async variants) and SRV
* (service) records ([method@Gio.Resolver.lookup_service]).
*
* The default resolver (see g_resolver_get_default()) has a timeout of 30s set
* on it since GLib 2.78. Earlier versions of GLib did not support resolver
* timeouts.
* [class@Gio.NetworkAddress] and [class@Gio.NetworkService] provide wrappers
* around `GResolver` functionality that also implement
* [iface@Gio.SocketConnectable], making it easy to connect to a remote
* host/service.
*
* The default resolver (see [func@Gio.Resolver.get_default]) has a timeout of
* 30s set on it since GLib 2.78. Earlier versions of GLib did not support
* resolver timeouts.
*
* This is an abstract type; subclasses of it implement different resolvers for
* different platforms and situations.
*/
typedef enum {
@ -83,15 +88,6 @@ struct _GResolverPrivate {
#endif
};
/**
* GResolver:
*
* The object that handles DNS resolution. Use g_resolver_get_default()
* to get the default resolver.
*
* This is an abstract type; subclasses of it implement different resolvers for
* different platforms and situations.
*/
G_DEFINE_ABSTRACT_TYPE_WITH_CODE (GResolver, g_resolver, G_TYPE_OBJECT,
G_ADD_PRIVATE (GResolver)
g_networking_init ();)

193
gio/gresource.c
View File

@ -48,69 +48,72 @@ static void register_lazy_static_resources (void);
G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
/**
* SECTION:gresource
* @short_description: Resource framework
* @include: gio/gio.h
* GResource:
*
* Applications and libraries often contain binary or textual data that is
* really part of the application, rather than user data. For instance
* #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files,
* icons, etc. These are often shipped as files in `$datadir/appname`, or
* manually included as literal strings in the code.
* [class@Gtk.Builder] `.ui` files, splashscreen images, [class@Gio.Menu] markup
* XML, CSS files, icons, etc. These are often shipped as files in
* `$datadir/appname`, or manually included as literal strings in the code.
*
* The #GResource API and the [glib-compile-resources][glib-compile-resources] program
* provide a convenient and efficient alternative to this which has some nice properties. You
* maintain the files as normal files, so its easy to edit them, but during the build the files
* are combined into a binary bundle that is linked into the executable. This means that loading
* the resource files are efficient (as they are already in memory, shared with other instances) and
* simple (no need to check for things like I/O errors or locate the files in the filesystem). It
* The `GResource` API and the
* [`glib-compile-resources`](glib-compile-resources.html) program provide a
* convenient and efficient alternative to this which has some nice properties.
* You maintain the files as normal files, so it’s easy to edit them, but during
* the build the files are combined into a binary bundle that is linked into the
* executable. This means that loading the resource files are efficient (as they
* are already in memory, shared with other instances) and simple (no need to
* check for things like I/O errors or locate the files in the filesystem). It
* also makes it easier to create relocatable applications.
*
* Resource files can also be marked as compressed. Such files will be included in the resource bundle
* in a compressed form, but will be automatically uncompressed when the resource is used. This
* is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
* Resource files can also be marked as compressed. Such files will be included
* in the resource bundle in a compressed form, but will be automatically
* uncompressed when the resource is used. This is very useful e.g. for larger
* text files that are parsed once (or rarely) and then thrown away.
*
* Resource files can also be marked to be preprocessed, by setting the value of the
* `preprocess` attribute to a comma-separated list of preprocessing options.
* The only options currently supported are:
*
* `xml-stripblanks` which will use the xmllint command
* to strip ignorable whitespace from the XML file. For this to work,
* the `XMLLINT` environment variable must be set to the full path to
* the xmllint executable, or xmllint must be in the `PATH`; otherwise
* the preprocessing step is skipped.
* - `xml-stripblanks` which will use the [`xmllint`](man:xmllint(1)) command
* to strip ignorable whitespace from the XML file. For this to work,
* the `XMLLINT` environment variable must be set to the full path to
* the xmllint executable, or xmllint must be in the `PATH`; otherwise
* the preprocessing step is skipped.
*
* `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
* `gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format,
* which allows you to create pixbufs directly using the data inside the
* resource file, rather than an (uncompressed) copy of it. For this, the
* `gdk-pixbuf-pixdata` program must be in the `PATH`, or the
* `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the
* `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort.
* `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource
* supports embedding modern image formats just as well. Instead of using it,
* embed a PNG or SVG file in your #GResource.
* - `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
* `gdk-pixbuf-pixdata` command to convert images to the [class@Gdk.Pixdata]
* format, which allows you to create pixbufs directly using the data inside
* the resource file, rather than an (uncompressed) copy of it. For this, the
* `gdk-pixbuf-pixdata` program must be in the `PATH`, or the
* `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to
* the `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will
* abort. `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as
* `GResource` supports embedding modern image formats just as well. Instead
* of using it, embed a PNG or SVG file in your `GResource`.
*
* `json-stripblanks` which will use the `json-glib-format` command to strip
* ignorable whitespace from the JSON file. For this to work, the
* `JSON_GLIB_FORMAT` environment variable must be set to the full path to the
* `json-glib-format` executable, or it must be in the `PATH`;
* otherwise the preprocessing step is skipped. In addition, at least version
* 1.6 of `json-glib-format` is required.
* - `json-stripblanks` which will use the
* [`json-glib-format`](man:json-glib-format(1)) command to strip ignorable
* whitespace from the JSON file. For this to work, the `JSON_GLIB_FORMAT`
* environment variable must be set to the full path to the
* `json-glib-format` executable, or it must be in the `PATH`; otherwise the
* preprocessing step is skipped. In addition, at least version 1.6 of
* `json-glib-format` is required.
*
* Resource files will be exported in the GResource namespace using the
* Resource files will be exported in the `GResource` namespace using the
* combination of the given `prefix` and the filename from the `file` element.
* The `alias` attribute can be used to alter the filename to expose them at a
* different location in the resource namespace. Typically, this is used to
* include files from a different source directory without exposing the source
* directory in the resource namespace, as in the example below.
*
* Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program
* which takes an XML file that describes the bundle, and a set of files that the XML references. These
* are combined into a binary resource bundle.
* Resource bundles are created by the
* [`glib-compile-resources`](glib-compile-resources.html) program
* which takes an XML file that describes the bundle, and a set of files that
* the XML references. These are combined into a binary resource bundle.
*
* An example resource description:
* |[
* ```xml
* <?xml version="1.0" encoding="UTF-8"?>
* <gresources>
* <gresource prefix="/org/gtk/Example">
@ -120,74 +123,92 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
* <file alias="example.css">data/example.css</file>
* </gresource>
* </gresources>
* ]|
* ```
*
* This will create a resource bundle with the following files:
* |[
* ```
* /org/gtk/Example/data/splashscreen.png
* /org/gtk/Example/dialog.ui
* /org/gtk/Example/menumarkup.xml
* /org/gtk/Example/example.css
* ]|
* ```
*
* Note that all resources in the process share the same namespace, so use Java-style
* path prefixes (like in the above example) to avoid conflicts.
* Note that all resources in the process share the same namespace, so use
* Java-style path prefixes (like in the above example) to avoid conflicts.
*
* You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a
* binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
* --generate-header arguments to create a source file and header to link directly into your application.
* You can then use [`glib-compile-resources`](glib-compile-resources.html) to
* compile the XML to a binary bundle that you can load with
* [func@Gio.Resource.load]. However, it’s more common to use the
* `--generate-source` and `--generate-header` arguments to create a source file
* and header to link directly into your application.
* This will generate `get_resource()`, `register_resource()` and
* `unregister_resource()` functions, prefixed by the `--c-name` argument passed
* to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns
* the generated #GResource object. The register and unregister functions
* register the resource so its files can be accessed using
* g_resources_lookup_data().
* to [`glib-compile-resources`](glib-compile-resources.html). `get_resource()`
* returns the generated `GResource` object. The register and unregister
* functions register the resource so its files can be accessed using
* [func@Gio.resources_lookup_data].
*
* Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
* using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
* to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
* the resource data.
* Once a `GResource` has been created and registered all the data in it can be
* accessed globally in the process by using API calls like
* [func@Gio.resources_open_stream] to stream the data or
* [func@Gio.resources_lookup_data] to get a direct pointer to the data. You can
* also use URIs like `resource:///org/gtk/Example/data/splashscreen.png` with
* [iface@Gio.File] to access the resource data.
*
* Some higher-level APIs, such as #GtkApplication, will automatically load
* resources from certain well-known paths in the resource namespace as a
* Some higher-level APIs, such as [class@Gtk.Application], will automatically
* load resources from certain well-known paths in the resource namespace as a
* convenience. See the documentation for those APIs for details.
*
* There are two forms of the generated source, the default version uses the compiler support for constructor
* and destructor functions (where available) to automatically create and register the #GResource on startup
* or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created
* instead. This requires an explicit initialization call in your application/library, but it works on all platforms,
* even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.)
* There are two forms of the generated source, the default version uses the
* compiler support for constructor and destructor functions (where available)
* to automatically create and register the `GResource` on startup or library
* load time. If you pass `--manual-register`, two functions to
* register/unregister the resource are created instead. This requires an
* explicit initialization call in your application/library, but it works on all
* platforms, even on the minor ones where constructors are not supported.
* (Constructor support is available for at least Win32, Mac OS and Linux.)
*
* Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
* during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
* when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
* are for your own resources, and resource data is often used once, during parsing, and then released.
* Note that resource data can point directly into the data segment of e.g. a
* library, so if you are unloading libraries during runtime you need to be very
* careful with keeping around pointers to data from a resource, as this goes
* away when the library is unloaded. However, in practice this is not generally
* a problem, since most resource accesses are for your own resources, and
* resource data is often used once, during parsing, and then released.
*
* When debugging a program or testing a change to an installed version, it is often useful to be able to
* replace resources in the program or library, without recompiling, for debugging or quick hacking and testing
* purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay
* resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform
* during resource lookups. It is ignored when running in a setuid process.
* # Overlays
*
* When debugging a program or testing a change to an installed version, it is
* often useful to be able to replace resources in the program or library,
* without recompiling, for debugging or quick hacking and testing purposes.
* Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment
* variable to selectively overlay resources with replacements from the
* filesystem. It is a `G_SEARCHPATH_SEPARATOR`-separated list of substitutions
* to perform during resource lookups. It is ignored when running in a setuid
* process.
*
* A substitution has the form
*
* |[
* /org/gtk/libgtk=/home/desrt/gtk-overlay
* ]|
* ```
* /org/gtk/libgtk=/home/desrt/gtk-overlay
* ```
*
* The part before the `=` is the resource subpath for which the overlay applies. The part after is a
* filesystem path which contains files and subdirectories as you would like to be loaded as resources with the
* The part before the `=` is the resource subpath for which the overlay
* applies. The part after is a filesystem path which contains files and
* subdirectories as you would like to be loaded as resources with the
* equivalent names.
*
* In the example above, if an application tried to load a resource with the resource path
* `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path
* `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an
* overlay, not an outright replacement, which means that if a file is not found at that path, the built-in
* version will be used instead. Whiteouts are not currently supported.
* In the example above, if an application tried to load a resource with the
* resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then `GResource` would check
* the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was
* found there, it would be used instead. This is an overlay, not an outright
* replacement, which means that if a file is not found at that path, the
* built-in version will be used instead. Whiteouts are not currently
* supported.
*
* Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after
* the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the
* location of a single resource with an individual file.
* Substitutions must start with a slash, and must not contain a trailing slash
* before the `=`. The path after the slash should ideally be absolute, but
* this is not strictly required. It is possible to overlay the location of a
* single resource with an individual file.
*
* Since: 2.32
*/

22
gio/gsimpleaction.c
View File

@ -26,25 +26,15 @@
#include "gaction.h"
#include "glibintl.h"
/**
* SECTION:gsimpleaction
* @title: GSimpleAction
* @short_description: A simple GAction implementation
* @include: gio/gio.h
*
* A #GSimpleAction is the obvious simple implementation of the #GAction
* interface. This is the easiest way to create an action for purposes of
* adding it to a #GSimpleActionGroup.
*
* See also #GtkAction.
*/
/**
* GSimpleAction:
*
* #GSimpleAction is an opaque data structure and can only be accessed
* using the following functions.
**/
* A `GSimpleAction` is the obvious simple implementation of the
* [iface@Gio.Action] interface. This is the easiest way to create an action for
* purposes of adding it to a [class@Gio.SimpleActionGroup].
*
* See also [class@Gtk.Action].
*/
struct _GSimpleAction
{

12
gio/gsimpleactiongroup.c
View File

@ -28,13 +28,13 @@
#include "gaction.h"
/**
* SECTION:gsimpleactiongroup
* @title: GSimpleActionGroup
* @short_description: A simple GActionGroup implementation
* @include: gio/gio.h
* GSimpleActionGroup:
*
* #GSimpleActionGroup is a hash table filled with #GAction objects,
* implementing the #GActionGroup and #GActionMap interfaces.
* `GSimpleActionGroup` is a hash table filled with [iface@Gio.Action] objects,
* implementing the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap]
* interfaces.
*
* Since: 2.28
**/
struct _GSimpleActionGroupPrivate

7
gio/gsimpleactiongroup.h
View File

@ -46,13 +46,6 @@ G_BEGIN_DECLS
typedef struct _GSimpleActionGroupPrivate GSimpleActionGroupPrivate;
typedef struct _GSimpleActionGroupClass GSimpleActionGroupClass;
/**
* GSimpleActionGroup:
*
* The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API.
*
* Since: 2.28
*/
struct _GSimpleActionGroup
{
/*< private >*/

28
gio/gsrvtarget.c
View File

@ -31,24 +31,24 @@
/**
* SECTION:gsrvtarget
* @short_description: DNS SRV record target
* @include: gio/gio.h
* GSrvTarget:
*
* A single target host/port that a network service is running on.
*
* SRV (service) records are used by some network protocols to provide
* service-specific aliasing and load-balancing. For example, XMPP
* (Jabber) uses SRV records to locate the XMPP server for a domain;
* rather than connecting directly to "example.com" or assuming a
* specific server hostname like "xmpp.example.com", an XMPP client
* would look up the "xmpp-client" SRV record for "example.com", and
* rather than connecting directly to ‘example.com’ or assuming a
* specific server hostname like ‘xmpp.example.com’, an XMPP client
* would look up the `xmpp-client` SRV record for ‘example.com’, and
* then connect to whatever host was pointed to by that record.
*
* You can use g_resolver_lookup_service() or
* g_resolver_lookup_service_async() to find the #GSrvTargets
* You can use [method@Gio.Resolver.lookup_service] or
* [method@Gio.Resolver.lookup_service_async] to find the `GSrvTarget`s
* for a given service. However, if you are simply planning to connect
* to the remote service, you can use #GNetworkService's
* #GSocketConnectable interface and not need to worry about
* #GSrvTarget at all.
* to the remote service, you can use [class@Gio.NetworkService]’s
* [iface@Gio.SocketConnectable] interface and not need to worry about
* `GSrvTarget` at all.
*/
struct _GSrvTarget {
@ -59,12 +59,6 @@ struct _GSrvTarget {
guint16 weight;
};
/**
* GSrvTarget:
*
* A single target host/port that a network service is running on.
*/
G_DEFINE_BOXED_TYPE (GSrvTarget, g_srv_target,
g_srv_target_copy, g_srv_target_free)

7
gio/gsubprocesslauncher.c
View File

@ -17,16 +17,13 @@
*/
/**
* SECTION:gsubprocesslauncher
* @title: GSubprocess Launcher
* @short_description: Environment options for launching a child process
* @include: gio/gio.h
* GSubprocessLauncher:
*
* This class contains a set of options for launching child processes,
* such as where its standard input and output will be directed, the
* argument list, the environment, and more.
*
* While the #GSubprocess class has high level functions covering
* While the [class@Gio.Subprocess] class has high level functions covering
* popular cases, use of this class allows access to more advanced
* options. It can also be used to launch multiple subprocesses with
* a similar configuration.

8
gio/gtcpconnection.c
View File

@ -13,13 +13,9 @@
*/
/**
* SECTION:gtcpconnection
* @title: GTcpConnection
* @short_description: A TCP GSocketConnection
* @include: gio/gio.h
* @see_also: #GSocketConnection.
* GTcpConnection:
*
* This is the subclass of #GSocketConnection that is created
* This is the subclass of [class@Gio.SocketConnection] that is created
* for TCP/IP sockets.
*
* Since: 2.22

25
gio/gtcpwrapperconnection.c
View File

@ -21,29 +21,18 @@
*/
/**
* SECTION:gtcpwrapperconnection
* @title: GTcpWrapperConnection
* @short_description: Wrapper for non-GSocketConnection-based,
* GSocket-based GIOStreams
* @include: gio/gio.h
* @see_also: #GSocketConnection.
* GTcpWrapperConnection:
*
* A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
* based on a #GSocket, but which is not actually a
* #GSocketConnection. This is used by #GSocketClient so that it can
* always return a #GSocketConnection, even when the connection it has
* actually created is not directly a #GSocketConnection.
* A `GTcpWrapperConnection` can be used to wrap a [class@Gio.IOStream] that is
* based on a [class@Gio.Socket], but which is not actually a
* [class@Gio.SocketConnection]. This is used by [class@Gio.SocketClient] so
* that it can always return a [class@Gio.SocketConnection], even when the
* connection it has actually created is not directly a
* [class@Gio.SocketConnection].
*
* Since: 2.28
*/
/**
* GTcpWrapperConnection:
*
* #GTcpWrapperConnection is an opaque data structure and can only be accessed
* using the following functions.
**/
#include "config.h"
#include "gtcpwrapperconnection.h"

81
gio/gtestdbus.c
View File

@ -333,25 +333,23 @@ _g_test_watcher_remove_pid (GPid pid)
/* GTestDBus object implementation */
/**
* SECTION:gtestdbus
* @short_description: D-Bus testing helper
* @include: gio/gio.h
* GTestDBus:
*
* A helper class for testing code which uses D-Bus without touching the user's
* A helper class for testing code which uses D-Bus without touching the user’s
* session bus.
*
* Note that #GTestDBus modifies the user’s environment, calling setenv().
* This is not thread-safe, so all #GTestDBus calls should be completed before
* threads are spawned, or should have appropriate locking to ensure no access
* conflicts to environment variables shared between #GTestDBus and other
* threads.
* Note that `GTestDBus` modifies the user’s environment, calling
* [`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus`
* calls should be completed before threads are spawned, or should have
* appropriate locking to ensure no access conflicts to environment variables
* shared between `GTestDBus` and other threads.
*
* ## Creating unit tests using GTestDBus
* ## Creating unit tests using `GTestDBus`
*
* Testing of D-Bus services can be tricky because normally we only ever run
* D-Bus services over an existing instance of the D-Bus daemon thus we
* usually don't activate D-Bus services that are not yet installed into the
* target system. The #GTestDBus object makes this easier for us by taking care
* usually don’t activate D-Bus services that are not yet installed into the
* target system. The `GTestDBus` object makes this easier for us by taking care
* of the lower level tasks such as running a private D-Bus daemon and looking
* up uninstalled services in customizable locations, typically in your source
* code tree.
@ -364,20 +362,24 @@ _g_test_watcher_remove_pid (GPid pid)
* uninstalled service executable in your source tree. Using autotools we would
* achieve this by adding a file such as `my-server.service.in` in the services
* directory and have it processed by configure.
* |[
* [D-BUS Service]
* Name=org.gtk.GDBus.Examples.ObjectManager
* Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
* ]|
*
* ```
* [D-BUS Service]
* Name=org.gtk.GDBus.Examples.ObjectManager
* Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
* ```
*
* You will also need to indicate this service directory in your test
* fixtures, so you will need to pass the path while compiling your
* test cases. Typically this is done with autotools with an added
* preprocessor flag specified to compile your tests such as:
* |[
* -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
* ]|
* Once you have a service definition file which is local to your source tree,
* you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
*
* ```
* -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
* ```
*
* Once you have a service definition file which is local to your source tree,
* you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding.
*
* An example of a test fixture for D-Bus services can be found
* here:
@ -386,42 +388,39 @@ _g_test_watcher_remove_pid (GPid pid)
* Note that these examples only deal with isolating the D-Bus aspect of your
* service. To successfully run isolated unit tests on your service you may need
* some additional modifications to your test case fixture. For example; if your
* service uses GSettings and installs a schema then it is important that your test service
* not load the schema in the ordinary installed location (chances are that your service
* and schema files are not yet installed, or worse; there is an older version of the
* schema file sitting in the install location).
* service uses [class@Gio.Settings] and installs a schema then it is important
* that your test service not load the schema in the ordinary installed location
* (chances are that your service and schema files are not yet installed, or
* worse; there is an older version of the schema file sitting in the install
* location).
*
* Most of the time we can work around these obstacles using the
* environment. Since the environment is inherited by the D-Bus daemon
* created by #GTestDBus and then in turn inherited by any services the
* created by `GTestDBus` and then in turn inherited by any services the
* D-Bus daemon activates, using the setup routine for your fixture is
* a practical place to help sandbox your runtime environment. For the
* rather typical GSettings case we can work around this by setting
* `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
* in the above fixture_setup() routine.
* in the above `fixture_setup()` routine.
*
* The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
* by compiling the schemas locally as a step before running test cases, an autotools setup might
* do the following in the directory holding schemas:
* |[
* The GSettings schemas need to be locally pre-compiled for this to work. This
* can be achieved by compiling the schemas locally as a step before running
* test cases, an autotools setup might do the following in the directory
* holding schemas:
*
* ```
* all-am:
* $(GLIB_COMPILE_SCHEMAS) .
*
* CLEANFILES += gschemas.compiled
* ]|
* ```
*
* Since: 2.34
*/
typedef struct _GTestDBusClass GTestDBusClass;
typedef struct _GTestDBusPrivate GTestDBusPrivate;
/**
* GTestDBus:
*
* The #GTestDBus structure contains only private data and
* should only be accessed using the provided API.
*
* Since: 2.34
*/
struct _GTestDBus {
GObject parent;

15
gio/gthemedicon.c
View File

@ -31,16 +31,15 @@
/**
* SECTION:gthemedicon
* @short_description: Icon theming support
* @include: gio/gio.h
* @see_also: #GIcon, #GLoadableIcon
* GThemedIcon:
*
* #GThemedIcon is an implementation of #GIcon that supports icon themes.
* #GThemedIcon contains a list of all of the icons present in an icon
* theme, so that icons can be looked up quickly. #GThemedIcon does
* `GThemedIcon` is an implementation of [iface@Gio.Icon] that supports icon
* themes.
*
* `GThemedIcon` contains a list of all of the icons present in an icon
* theme, so that icons can be looked up quickly. `GThemedIcon` does
* not provide actual pixmaps for icons, just the icon names.
* Ideally something like gtk_icon_theme_choose_icon() should be used to
* Ideally something like [method@Gtk.IconTheme.choose_icon] should be used to
* resolve the list of names so that fallback icons work nicely with
* themes that inherit other themes.
**/

5
gio/gthemedicon.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_THEMED_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_THEMED_ICON))
#define G_THEMED_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_THEMED_ICON, GThemedIconClass))
/**
* GThemedIcon:
*
* An implementation of #GIcon for themed icons.
**/
typedef struct _GThemedIconClass GThemedIconClass;
GIO_AVAILABLE_IN_ALL

19
gio/gthreadedsocketservice.c
View File

@ -23,27 +23,24 @@
*/
/**
* SECTION:gthreadedsocketservice
* @title: GThreadedSocketService
* @short_description: A threaded GSocketService
* @include: gio/gio.h
* @see_also: #GSocketService.
* GThreadedSocketService:
*
* A #GThreadedSocketService is a simple subclass of #GSocketService
* A `GThreadedSocketService` is a simple subclass of [class@Gio.SocketService]
* that handles incoming connections by creating a worker thread and
* dispatching the connection to it by emitting the
* #GThreadedSocketService::run signal in the new thread.
* [signal@Gio.ThreadedSocketService::run signal] in the new thread.
*
* The signal handler may perform blocking IO and need not return
* The signal handler may perform blocking I/O and need not return
* until the connection is closed.
*
* The service is implemented using a thread pool, so there is a
* limited amount of threads available to serve incoming requests.
* The service automatically stops the #GSocketService from accepting
* The service automatically stops the [class@Gio.SocketService] from accepting
* new connections when all threads are busy.
*
* As with #GSocketService, you may connect to #GThreadedSocketService::run,
* or subclass and override the default handler.
* As with [class@Gio.SocketService], you may connect to
* [signal@Gio.ThreadedSocketService::run], or subclass and override the default
* handler.
*/
#include "config.h"

16
gio/gtlsfiledatabase.c
View File

@ -30,25 +30,15 @@
#include "glibintl.h"
/**
* SECTION:gtlsfiledatabase
* @short_description: TLS file based database type
* @include: gio/gio.h
* GTlsFileDatabase:
*
* #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
* their certificate information from a file. It is an interface which
* `GTlsFileDatabase` is implemented by [class@Gio.TlsDatabase] objects which
* load their certificate information from a file. It is an interface which
* TLS library specific subtypes implement.
*
* Since: 2.30
*/
/**
* GTlsFileDatabase:
*
* Implemented by a #GTlsDatabase which allows you to load certificates
* from a file.
*
* Since: 2.30
*/
G_DEFINE_INTERFACE (GTlsFileDatabase, g_tls_file_database, G_TYPE_TLS_DATABASE)
static void

25
gio/gtlsinteraction.c
View File

@ -36,37 +36,28 @@
/**
* SECTION:gtlsinteraction
* @short_description: Interaction with the user during TLS operations.
* @include: gio/gio.h
* GTlsInteraction:
*
* #GTlsInteraction provides a mechanism for the TLS connection and database
* `GTlsInteraction` provides a mechanism for the TLS connection and database
* code to interact with the user. It can be used to ask the user for passwords.
*
* To use a #GTlsInteraction with a TLS connection use
* g_tls_connection_set_interaction().
* To use a `GTlsInteraction` with a TLS connection use
* [method@Gio.TlsConnection.set_interaction].
*
* Callers should instantiate a derived class that implements the various
* interaction methods to show the required dialogs.
*
* Callers should use the 'invoke' functions like
* g_tls_interaction_invoke_ask_password() to run interaction methods. These
* functions make sure that the interaction is invoked in the main loop
* [method@Gio.TlsInteraction.invoke_ask_password] to run interaction methods.
* These functions make sure that the interaction is invoked in the main loop
* and not in the current thread, if the current thread is not running the
* main loop.
*
* Derived classes can choose to implement whichever interactions methods they'd
* Derived classes can choose to implement whichever interactions methods they’d
* like to support by overriding those virtual methods in their class
* initialization function. Any interactions not implemented will return
* %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
* `G_TLS_INTERACTION_UNHANDLED`. If a derived class implements an async method,
* it must also implement the corresponding finish method.
*/
/**
* GTlsInteraction:
*
* An object representing interaction that the TLS connection and database
* might have with the user.
*
* Since: 2.30
*/

9
gio/gtlspassword.c
View File

@ -29,15 +29,6 @@
#include <string.h>
/**
* SECTION:gtlspassword
* @title: GTlsPassword
* @short_description: TLS Passwords for prompting
* @include: gio/gio.h
*
* Holds a password used in TLS.
*/
/**
* GTlsPassword:
*

22
gio/gunixfdlist.c
View File

@ -15,18 +15,15 @@
*/
/**
* SECTION:gunixfdlist
* @title: GUnixFDList
* @short_description: An object containing a set of UNIX file descriptors
* @include: gio/gunixfdlist.h
* @see_also: #GUnixFDMessage
* GUnixFDList:
*
* A #GUnixFDList contains a list of file descriptors. It owns the file
* A `GUnixFDList` contains a list of file descriptors. It owns the file
* descriptors that it contains, closing them when finalized.
*
* It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
* the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message()
* and received using g_socket_receive_message().
* It may be wrapped in a [class@Gio.UnixFDMessage] and sent over a
* [class@Gio.Socket] in the `G_SOCKET_FAMILY_UNIX` family by using
* [method@Gio.Socket.send_message] and received using
* [method@Gio.Socket.receive_message].
*
* Before 2.74, `<gio/gunixfdlist.h>` belonged to the UNIX-specific GIO
* interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when
@ -35,13 +32,6 @@
* Since 2.74, the API is available for Windows.
*/
/**
* GUnixFDList:
*
* #GUnixFDList is an opaque data structure and can only be accessed
* using the following functions.
**/
#include "config.h"
#include <fcntl.h>