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

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

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

See merge request GNOME/glib!3712
This commit is contained in:
Philip Withnall 2023-11-21 12:56:04 +00:00
commit f2d7e6af22
20 changed files with 186 additions and 225 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -46,15 +46,23 @@ content_files = [
"error.md",
"pollable-utils.md",
"unix-mounts.md",
"dbus-error.md",
"dbus-introspection.md",
"dbus-name-owning.md",
"dbus-name-watching.md",
"dbus-utils.md",
"menu-exporter.md",
"networking.md",
"migrating-gdbus.md",
"migrating-gconf.md",
"migrating-gnome-vfs.md",
"io-scheduler.md",
]
content_images = [
"gvfs-overview.png",

20
docs/reference/gio/io-scheduler.md Normal file
View File

@ -0,0 +1,20 @@
Title: GIOScheduler
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Andrew Walton
# GIOScheduler
Schedules asynchronous I/O operations. `GIOScheduler` integrates
into the main event loop ([struct@GLib.MainLoop]) and uses threads.
Deprecated: 2.36: As of GLib 2.36, `GIOScheduler` is deprecated in favor of
[struct@GLib.ThreadPool] and [class@Gio.Task].
The `GIOScheduler` API is:
* [type@Gio.IOSchedulerJobFunc]
* [func@Gio.io_scheduler_push_job]
* [func@Gio.io_scheduler_cancel_all_jobs]
* [type@Gio.IOSchedulerJob]
* [method@Gio.IOSchedulerJob.send_to_mainloop]
* [method@Gio.IOSchedulerJob.send_to_mainloop_async]

15
docs/reference/gio/menu-exporter.md Normal file
View File

@ -0,0 +1,15 @@
Title: GMenuModel Exporter
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2011 Matthias Clasen
# GMenuModel Exporter
These functions support exporting a [class@Gio.MenuModel] on D-Bus. The D-Bus
interface that is used is a private implementation detail.
* [method@Gio.DBusConnection.export_menu_model]
* [method@Gio.DBusConnection.unexport_menu_model]
To access an exported [class@Gio.MenuModel] remotely, use
[func@Gio.DBusMenuModel.get] to obtain a [class@Gio.DBusMenuModel].

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

@ -232,11 +232,16 @@ expand_content_files = [
'dbus-utils.md',
'error.md',
'file-attributes.md',
'io-scheduler.md',
'menu-exporter.md',
'migrating-gconf.md',
'migrating-gdbus.md',
'migrating-gnome-vfs.md',
'networking.md',
'overview.md',
'pollable-utils.md',
'tls-overview.md',
'unix-mounts.md',
]
gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf)

29
docs/reference/gio/networking.md Normal file
View File

@ -0,0 +1,29 @@
Title: gnetworking.h
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 Dan Winship
# gnetworking.h
The `<gio/gnetworking.h>` header can be included to get
various low-level networking-related system headers, automatically
taking care of certain portability issues for you.
This can be used, for example, if you want to call
[`setsockopt()`](man:setsockopt(2)) on a [class@Gio.Socket].
Note that while WinSock has many of the same APIs as the
traditional UNIX socket API, most of them behave at least slightly
differently (particularly with respect to error handling). If you
want your code to work under both UNIX and Windows, you will need
to take these differences into account.
Also, under GNU libc, certain non-portable functions are only visible
in the headers if you define `_GNU_SOURCE` before including them. Note
that this symbol must be defined before including any headers, or it
may not take effect.
There is one function provided specifically for initialising the networking
APIs, which needs to be called only if they are being used before GLib
initialises itself:
* [func@Gio.networking_init]

15
docs/reference/gio/pollable-utils.md Normal file
View File

@ -0,0 +1,15 @@
Title: Pollable Utility Functions
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2012 Dan Winship
# Pollable Utility Functions
Utility functions for [iface@Gio.PollableInputStream] and
[iface@Gio.PollableOutputStream] implementations.
* [func@Gio.pollable_source_new]
* [func@Gio.pollable_source_new_full]
* [func@Gio.pollable_stream_read]
* [func@Gio.pollable_stream_write]
* [func@Gio.pollable_stream_write_all]

35
docs/reference/gio/unix-mounts.md Normal file
View File

@ -0,0 +1,35 @@
Title: UNIX Mounts
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Andrew Walton
SPDX-FileCopyrightText: 2008 Matthias Clasen
# UNIX Mounts
Routines for managing mounted UNIX mount points and paths.
Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
file when using it.
There are three main classes:
* [struct@Gio.UnixMountEntry]
* [struct@Gio.UnixMountPoint]
* [class@Gio.UnixMountMonitor]
Various helper functions for querying mounts:
* [func@Gio.unix_mount_points_get]
* [func@Gio.UnixMountPoint.at]
* [func@Gio.unix_mounts_get]
* [func@Gio.unix_mount_at]
* [func@Gio.unix_mount_for]
* [func@Gio.unix_mounts_changed_since]
* [func@Gio.unix_mount_points_changed_since]
And several helper functions for checking the type of a mount or path:
* [func@Gio.unix_is_mount_path_system_internal]
* [func@Gio.unix_is_system_fs_type]
* [func@Gio.unix_is_system_device_path]

3
gio/gfileiostream.c
View File

@ -190,7 +190,8 @@ async_ready_callback_wrapper (GObject *source_object,
* g_file_io_stream_query_info_async:
* @stream: a #GFileIOStream.
* @attributes: a file attribute query string.
* @io_priority: the [I/O priority][gio-GIOScheduler] of the request
* @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the
* request
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback
* to call when the request is satisfied

3
gio/gfileoutputstream.c
View File

@ -187,7 +187,8 @@ async_ready_callback_wrapper (GObject *source_object,
* g_file_output_stream_query_info_async:
* @stream: a #GFileOutputStream.
* @attributes: a file attribute query string.
* @io_priority: the [I/O priority][gio-GIOScheduler] of the request
* @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the
* request
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: callback to call when the request is satisfied
* @user_data: the data to pass to callback function

20
gio/gioscheduler.c
View File

@ -26,18 +26,6 @@
#include "gcancellable.h"
#include "gtask.h"
/**
* SECTION:gioscheduler
* @short_description: I/O Scheduler
* @include: gio/gio.h
*
* As of GLib 2.36, #GIOScheduler is deprecated in favor of
* #GThreadPool and #GTask.
*
* Schedules asynchronous I/O operations. #GIOScheduler integrates
* into the main event loop (#GMainLoop) and uses threads.
*/
struct _GIOSchedulerJob {
GList *active_link;
GTask *task;
@ -110,7 +98,7 @@ io_job_thread (GTask *task,
* by calling g_cancellable_cancel() or by calling
* g_io_scheduler_cancel_all_jobs().
*
* Deprecated: use #GThreadPool or g_task_run_in_thread()
* Deprecated: 2.36: use #GThreadPool or g_task_run_in_thread()
**/
void
g_io_scheduler_push_job (GIOSchedulerJobFunc job_func,
@ -157,7 +145,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
* A job is cancellable if a #GCancellable was passed into
* g_io_scheduler_push_job().
*
* Deprecated: You should never call this function, since you don't
* Deprecated: 2.36: You should never call this function, since you don't
* know how other libraries in your program might be making use of
* gioscheduler.
**/
@ -236,7 +224,7 @@ mainloop_proxy_free (MainLoopProxy *proxy)
*
* Returns: The return value of @func
*
* Deprecated: Use g_main_context_invoke().
* Deprecated: 2.36: Use g_main_context_invoke().
**/
gboolean
g_io_scheduler_job_send_to_mainloop (GIOSchedulerJob *job,
@ -295,7 +283,7 @@ g_io_scheduler_job_send_to_mainloop (GIOSchedulerJob *job,
* @func is called, either by passing %NULL as @notify to
* g_io_scheduler_push_job() or by using refcounting for @user_data.
*
* Deprecated: Use g_main_context_invoke().
* Deprecated: 2.36: Use g_main_context_invoke().
**/
void
g_io_scheduler_job_send_to_mainloop_async (GIOSchedulerJob *job,

92
gio/giotypes.h
View File

@ -65,11 +65,6 @@ typedef struct _GPermission GPermission;
typedef struct _GMenuModel GMenuModel;
typedef struct _GNotification GNotification;
/**
* GDrive:
*
* Opaque drive object.
**/
typedef struct _GDrive GDrive; /* Dummy typedef */
typedef struct _GFileEnumerator GFileEnumerator;
typedef struct _GFileMonitor GFileMonitor;
@ -110,6 +105,9 @@ typedef struct _GIOExtension GIOExtension;
* GIOSchedulerJob:
*
* Opaque class for defining and scheduling IO jobs.
*
* Deprecated: 2.36: Use [struct@GLib.ThreadPool] or
* [method@Gio.Task.run_in_thread]
**/
typedef struct _GIOSchedulerJob GIOSchedulerJob;
typedef struct _GIOStreamAdapter GIOStreamAdapter;
@ -118,11 +116,6 @@ typedef struct _GBytesIcon GBytesIcon;
typedef struct _GMemoryInputStream GMemoryInputStream;
typedef struct _GMemoryOutputStream GMemoryOutputStream;
/**
* GMount:
*
* A handle to an object implementing the #GMountIface interface.
**/
typedef struct _GMount GMount; /* Dummy typedef */
typedef struct _GMountOperation GMountOperation;
typedef struct _GNetworkAddress GNetworkAddress;
@ -135,82 +128,24 @@ typedef struct _GPollableInputStream GPollableInputStream; /* Dummy typ
typedef struct _GPollableOutputStream GPollableOutputStream; /* Dummy typedef */
typedef struct _GResolver GResolver;
/**
* GResource:
*
* A resource bundle.
*
* Since: 2.32
*/
typedef struct _GResource GResource;
typedef struct _GSeekable GSeekable;
typedef struct _GSimpleAsyncResult GSimpleAsyncResult;
/**
* GSocket:
*
* A lowlevel network socket object.
*
* Since: 2.22
**/
typedef struct _GSocket GSocket;
typedef struct _GSocketControlMessage GSocketControlMessage;
/**
* GSocketClient:
*
* A helper class for network clients to make connections.
*
* Since: 2.22
**/
typedef struct _GSocketClient GSocketClient;
/**
* GSocketConnection:
*
* A socket connection GIOStream object for connection-oriented sockets.
*
* Since: 2.22
**/
typedef struct _GSocketConnection GSocketConnection;
/**
* GSocketListener:
*
* A helper class for network servers to listen for and accept connections.
*
* Since: 2.22
**/
typedef struct _GSocketListener GSocketListener;
/**
* GSocketService:
*
* A helper class for handling accepting incoming connections in the
* glib mainloop.
*
* Since: 2.22
**/
typedef struct _GSocketService GSocketService;
typedef struct _GSocketAddress GSocketAddress;
typedef struct _GSocketAddressEnumerator GSocketAddressEnumerator;
typedef struct _GSocketConnectable GSocketConnectable;
typedef struct _GSrvTarget GSrvTarget;
typedef struct _GTask GTask;
/**
* GTcpConnection:
*
* A #GSocketConnection for TCP/IP connections.
*
* Since: 2.22
**/
typedef struct _GTcpConnection GTcpConnection;
typedef struct _GTcpWrapperConnection GTcpWrapperConnection;
/**
* GThreadedSocketService:
*
* A helper class for handling accepting incoming connections in the
* glib mainloop and handling them in a thread.
*
* Since: 2.22
**/
typedef struct _GThreadedSocketService GThreadedSocketService;
typedef struct _GDtlsConnection GDtlsConnection;
typedef struct _GDtlsClientConnection GDtlsClientConnection; /* Dummy typedef */
@ -226,23 +161,11 @@ typedef struct _GTlsPassword GTlsPassword;
typedef struct _GTlsServerConnection GTlsServerConnection; /* Dummy typedef */
typedef struct _GVfs GVfs; /* Dummy typedef */
/**
* GProxyResolver:
*
* A helper class to enumerate proxies base on URI.
*
* Since: 2.26
**/
typedef struct _GProxyResolver GProxyResolver;
typedef struct _GProxy GProxy;
typedef struct _GProxyAddress GProxyAddress;
typedef struct _GProxyAddressEnumerator GProxyAddressEnumerator;
/**
* GVolume:
*
* Opaque mountable volume object.
**/
typedef struct _GVolume GVolume; /* Dummy typedef */
typedef struct _GVolumeMonitor GVolumeMonitor;
@ -357,6 +280,8 @@ typedef void (* GFileMeasureProgressCallback) (gboolean reporting,
*
* Returns: %TRUE if this function should be called again to
* complete the job, %FALSE if the job is complete (or cancelled)
* Deprecated: 2.36: Use [struct@GLib.ThreadPool] or
* [method@Gio.Task.run_in_thread]
**/
typedef gboolean (*GIOSchedulerJobFunc) (GIOSchedulerJob *job,
GCancellable *cancellable,
@ -626,13 +551,6 @@ typedef GType (*GDBusProxyTypeFunc) (GDBusObjectManagerClient *manager,
typedef struct _GTestDBus GTestDBus;
typedef struct _GSubprocess GSubprocess;
/**
* GSubprocessLauncher:
*
* Options for launching a child process.
*
* Since: 2.40
*/
typedef struct _GSubprocessLauncher GSubprocessLauncher;
G_END_DECLS

15
gio/gmenuexporter.c
View File

@ -28,21 +28,6 @@
#include "gdbusnamewatching.h"
#include "gdbuserror.h"
/**
* SECTION:gmenuexporter
* @title: GMenuModel exporter
* @short_description: Export GMenuModels on D-Bus
* @include: gio/gio.h
* @see_also: #GMenuModel, #GDBusMenuModel
*
* These functions support exporting a #GMenuModel on D-Bus.
* The D-Bus interface that is used is a private implementation
* detail.
*
* To access an exported #GMenuModel remotely, use
* g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
*/
/* {{{1 D-Bus Interface description */
/* For documentation of this interface, see

25
gio/gnetworking.c
View File

@ -25,31 +25,6 @@
#include "gnetworking.h"
#include "gnetworkingprivate.h"
/**
* SECTION:gnetworking
* @title: gnetworking.h
* @short_description: System networking includes
* @include: gio/gnetworking.h
*
* The `<gio/gnetworking.h>` header can be included to get
* various low-level networking-related system headers, automatically
* taking care of certain portability issues for you.
*
* This can be used, for example, if you want to call setsockopt()
* on a #GSocket.
*
* Note that while WinSock has many of the same APIs as the
* traditional UNIX socket API, most of them behave at least slightly
* differently (particularly with respect to error handling). If you
* want your code to work under both UNIX and Windows, you will need
* to take these differences into account.
*
* Also, under GNU libc, certain non-portable functions are only visible
* in the headers if you define %_GNU_SOURCE before including them. Note
* that this symbol must be defined before including any headers, or it
* may not take effect.
*/
/**
* g_networking_init:
*

9
gio/gpollableutils.c
View File

@ -26,15 +26,6 @@
#include "gasynchelper.h"
#include "glibintl.h"
/**
* SECTION:gpollableutils
* @short_description: Utilities for pollable streams
* @include: gio/gio.h
*
* Utility functions for #GPollableInputStream and
* #GPollableOutputStream implementations.
*/
typedef struct {
GSource source;

2
gio/gproxyresolver.c
View File

@ -46,6 +46,8 @@
* [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.
*
* Since: 2.26
*/
/**

2
gio/gthreadedsocketservice.c
View File

@ -41,6 +41,8 @@
* As with [class@Gio.SocketService], you may connect to
* [signal@Gio.ThreadedSocketService::run], or subclass and override the default
* handler.
*
* Since: 2.22
*/
#include "config.h"

12
gio/gunixmounts.c
View File

@ -87,18 +87,6 @@ extern char* hasmntopt(const struct mntent* mnt, const char* opt);
static const char *_resolve_dev_root (void);
#endif
/**
* SECTION:gunixmounts
* @include: gio/gunixmounts.h
* @short_description: UNIX mounts
*
* Routines for managing mounted UNIX mount points and paths.
*
* Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
* interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
* file when using it.
*/
/**
* GUnixMountType:
* @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type.

9
glib/ghmac.c
View File

@ -37,9 +37,7 @@
/**
* SECTION:hmac
* @title: Secure HMAC Digests
* @short_description: computes the HMAC for data
* GHmac:
*
* HMACs should be used when producing a cookie or hash based on data
* and a key. Simple mechanisms for using SHA1 and other algorithms to
@ -53,6 +51,11 @@
*
* Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512
* in GLib 2.42. Support for SHA-384 was added in GLib 2.52.
*
* To create a new `GHmac`, use [ctor@GLib.Hmac.new]. To free a `GHmac`, use
* [method@GLib.Hmac.unref].
*
* Since: 2.30
*/
struct _GHmac

9
glib/ghmac.h
View File

@ -30,15 +30,6 @@
G_BEGIN_DECLS
/**
* GHmac:
*
* An opaque structure representing a HMAC operation.
* To create a new GHmac, use g_hmac_new(). To free
* a GHmac, use g_hmac_unref().
*
* Since: 2.30
*/
typedef struct _GHmac GHmac;
GLIB_AVAILABLE_IN_2_30

83
glib/giochannel.c
View File

@ -43,56 +43,45 @@
#include "glibintl.h"
/**
* SECTION:iochannels
* @title: IO Channels
* @short_description: portable support for using files, pipes and sockets
* @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(),
* #GMainLoop
*
* The #GIOChannel data type aims to provide a portable method for
* using file descriptors, pipes, and sockets, and integrating them
* into the [main event loop][glib-The-Main-Event-Loop]. Currently,
* full support is available on UNIX platforms, support for Windows
* is only partially complete.
*
* To create a new #GIOChannel on UNIX systems use
* g_io_channel_unix_new(). This works for plain file descriptors,
* pipes and sockets. Alternatively, a channel can be created for a
* file in a system independent manner using g_io_channel_new_file().
*
* Once a #GIOChannel has been created, it can be used in a generic
* manner with the functions g_io_channel_read_chars(),
* g_io_channel_write_chars(), g_io_channel_seek_position(), and
* g_io_channel_shutdown().
*
* To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop],
* use g_io_add_watch() or g_io_add_watch_full(). Here you specify which
* events you are interested in on the #GIOChannel, and provide a
* function to be called whenever these events occur.
*
* #GIOChannel instances are created with an initial reference count of 1.
* g_io_channel_ref() and g_io_channel_unref() can be used to
* increment or decrement the reference count respectively. When the
* reference count falls to 0, the #GIOChannel is freed. (Though it
* isn't closed automatically, unless it was created using
* g_io_channel_new_file().) Using g_io_add_watch() or
* g_io_add_watch_full() increments a channel's reference count.
*
* The new functions g_io_channel_read_chars(),
* g_io_channel_read_line(), g_io_channel_read_line_string(),
* g_io_channel_read_to_end(), g_io_channel_write_chars(),
* g_io_channel_seek_position(), and g_io_channel_flush() should not be
* mixed with the deprecated functions g_io_channel_read(),
* g_io_channel_write(), and g_io_channel_seek() on the same channel.
**/
/**
* GIOChannel:
*
* A data structure representing an IO Channel. The fields should be
* considered private and should only be accessed with the following
* functions.
* The `GIOChannel` data type aims to provide a portable method for
* using file descriptors, pipes, and sockets, and integrating them
* into the main event loop (see [struct@GLib.MainContext]). Currently,
* full support is available on UNIX platforms; support for Windows
* is only partially complete.
*
* To create a new `GIOChannel` on UNIX systems use
* [ctor@GLib.IOChannel.unix_new]. This works for plain file descriptors,
* pipes and sockets. Alternatively, a channel can be created for a
* file in a system independent manner using [ctor@GLib.IOChannel.new_file].
*
* Once a `GIOChannel` has been created, it can be used in a generic
* manner with the functions [method@GLib.IOChannel.read_chars],
* [method@GLib.IOChannel.write_chars], [method@GLib.IOChannel.seek_position],
* and [method@GLib.IOChannel.shutdown].
*
* To add a `GIOChannel` to the main event loop, use [func@GLib.io_add_watch] or
* [func@GLib.io_add_watch_full]. Here you specify which events you are
* interested in on the `GIOChannel`, and provide a function to be called
* whenever these events occur.
*
* `GIOChannel` instances are created with an initial reference count of 1.
* [method@GLib.IOChannel.ref] and [method@GLib.IOChannel.unref] can be used to
* increment or decrement the reference count respectively. When the
* reference count falls to 0, the `GIOChannel` is freed. (Though it
* isn’t closed automatically, unless it was created using
* [ctor@GLib.IOChannel.new_file].) Using [func@GLib.io_add_watch] or
* [func@GLib.io_add_watch_full] increments a channel’s reference count.
*
* The new functions [method@GLib.IOChannel.read_chars],
* [method@GLib.IOChannel.read_line], [method@GLib.IOChannel.read_line_string],
* [method@GLib.IOChannel.read_to_end], [method@GLib.IOChannel.write_chars],
* [method@GLib.IOChannel.seek_position], and [method@GLib.IOChannel.flush]
* should not be mixed with the deprecated functions
* [method@GLib.IOChannel.read], [method@GLib.IOChannel.write], and
* [method@GLib.IOChannel.seek] on the same channel.
**/
/**