From 7e15d56013e46577131b7a2d015508069ac1a582 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:37:13 +0100 Subject: [PATCH 01/14] docs: Move the GDebugControllerDBus SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gdebugcontrollerdbus.c | 42 +++++++++++++++++++------------------- gio/gdebugcontrollerdbus.h | 7 ------- 2 files changed, 21 insertions(+), 28 deletions(-) diff --git a/gio/gdebugcontrollerdbus.c b/gio/gdebugcontrollerdbus.c index ce0f70383..79173cec0 100644 --- a/gio/gdebugcontrollerdbus.c +++ b/gio/gdebugcontrollerdbus.c @@ -31,35 +31,34 @@ #include "gio/gmarshal-internal.h" /** - * SECTION:gdebugcontrollerdbus - * @title: GDebugControllerDBus - * @short_description: Debugging controller D-Bus implementation - * @include: gio/gio.h + * GDebugControllerDBus: * - * #GDebugControllerDBus is an implementation of #GDebugController which exposes - * debug settings as a D-Bus object. + * `GDebugControllerDBus` is an implementation of [iface@Gio.DebugController] + * which exposes debug settings as a D-Bus object. * - * It is a #GInitable object, and will register an object at + * It is a [iface@Gio.Initable] object, and will register an object at * `/org/gtk/Debugging` on the bus given as - * #GDebugControllerDBus:connection once it’s initialized. The object will be - * unregistered when the last reference to the #GDebugControllerDBus is dropped. + * [property@Gio.DebugControllerDBus:connection] once it’s initialized. The + * object will be unregistered when the last reference to the + * `GDebugControllerDBus` is dropped. * * This D-Bus object can be used by remote processes to enable or disable debug * output in this process. Remote processes calling * `org.gtk.Debugging.SetDebugEnabled()` will affect the value of - * #GDebugController:debug-enabled and, by default, g_log_get_debug_enabled(). - * default. + * [property@Gio.DebugController:debug-enabled] and, by default, + * [func@GLib.log_get_debug_enabled]. * * By default, no processes are allowed to call `SetDebugEnabled()` unless a - * #GDebugControllerDBus::authorize signal handler is installed. This is because - * the process may be privileged, or might expose sensitive information in its - * debug output. You may want to restrict the ability to enable debug output to - * privileged users or processes. + * [signal@Gio.DebugControllerDBus::authorize] signal handler is installed. This + * is because the process may be privileged, or might expose sensitive + * information in its debug output. You may want to restrict the ability to + * enable debug output to privileged users or processes. * * One option is to install a D-Bus security policy which restricts access to * `SetDebugEnabled()`, installing something like the following in * `$datadir/dbus-1/system.d/`: - * |[ + * + * ```xml * * @@ -71,7 +70,7 @@ * * * - * ]| + * ``` * * This will prevent the `SetDebugEnabled()` method from being called by all * except root. It will not prevent the `DebugEnabled` property from being read, @@ -79,9 +78,10 @@ * * Another option is to use polkit to allow or deny requests on a case-by-case * basis, allowing for the possibility of dynamic authorisation. To do this, - * connect to the #GDebugControllerDBus::authorize signal and query polkit in - * it: - * |[ + * connect to the [signal@Gio.DebugControllerDBus::authorize] signal and query + * polkit in it: + * + * ```c * g_autoptr(GError) child_error = NULL; * g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL); * gulong debug_controller_authorize_id = 0; @@ -142,7 +142,7 @@ * * return polkit_authorization_result_get_is_authorized (auth_result); * } - * ]| + * ``` * * Since: 2.72 */ diff --git a/gio/gdebugcontrollerdbus.h b/gio/gdebugcontrollerdbus.h index c6e6c700c..17e365864 100644 --- a/gio/gdebugcontrollerdbus.h +++ b/gio/gdebugcontrollerdbus.h @@ -28,13 +28,6 @@ G_BEGIN_DECLS -/** - * GDebugControllerDBus: - * - * #GDebugControllerDBus is an implementation of #GDebugController over D-Bus. - * - * Since: 2.72 - */ #define G_TYPE_DEBUG_CONTROLLER_DBUS (g_debug_controller_dbus_get_type ()) GIO_AVAILABLE_IN_2_72 G_DECLARE_DERIVABLE_TYPE (GDebugControllerDBus, g_debug_controller_dbus, G, DEBUG_CONTROLLER_DBUS, GObject) From 0576e82e9add63ff8e64139d2b760954b4721080 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:37:35 +0100 Subject: [PATCH 02/14] docs: Move the GFileDescriptorBased SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gfiledescriptorbased.c | 12 +++++------- gio/gfiledescriptorbased.h | 5 ----- 2 files changed, 5 insertions(+), 12 deletions(-) diff --git a/gio/gfiledescriptorbased.c b/gio/gfiledescriptorbased.c index 53f55fec0..5ebdf6eca 100644 --- a/gio/gfiledescriptorbased.c +++ b/gio/gfiledescriptorbased.c @@ -26,20 +26,18 @@ /** - * SECTION:gfiledescriptorbased - * @short_description: Interface for file descriptor based IO - * @include: gio/gfiledescriptorbased.h - * @see_also: #GInputStream, #GOutputStream + * GFileDescriptorBased: * - * #GFileDescriptorBased is implemented by streams (implementations of - * #GInputStream or #GOutputStream) that are based on file descriptors. + * `GFileDescriptorBased` is an interface for file descriptor based IO. + * + * It is implemented by streams (implementations of [class@Gio.InputStream] or + * [class@Gio.OutputStream]) that are based on file descriptors. * * Note that `` belongs to the UNIX-specific * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config * file when using it. * * Since: 2.24 - * **/ typedef GFileDescriptorBasedIface GFileDescriptorBasedInterface; diff --git a/gio/gfiledescriptorbased.h b/gio/gfiledescriptorbased.h index 46fdbf525..a512feb50 100644 --- a/gio/gfiledescriptorbased.h +++ b/gio/gfiledescriptorbased.h @@ -33,11 +33,6 @@ G_BEGIN_DECLS #define G_FILE_DESCRIPTOR_BASED_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_FILE_DESCRIPTOR_BASED, GFileDescriptorBasedIface)) G_DEFINE_AUTOPTR_CLEANUP_FUNC(GFileDescriptorBased, g_object_unref) -/** - * GFileDescriptorBased: - * - * An interface for file descriptor based io objects. - **/ typedef struct _GFileDescriptorBasedIface GFileDescriptorBasedIface; /** From ca505f34f26ed8f0a9f81b43e6e74f3dd5373409 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:38:09 +0100 Subject: [PATCH 03/14] docs: Move the GFileEnumerator SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gfileenumerator.c | 28 +++++++++++++--------------- gio/gfileenumerator.h | 5 ----- 2 files changed, 13 insertions(+), 20 deletions(-) diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c index ee0f56338..abd54aaf0 100644 --- a/gio/gfileenumerator.c +++ b/gio/gfileenumerator.c @@ -39,23 +39,21 @@ struct _GFileEnumeratorPrivate { }; /** - * SECTION:gfileenumerator - * @short_description: Enumerated Files Routines - * @include: gio/gio.h + * GFileEnumerator: * - * #GFileEnumerator allows you to operate on a set of #GFiles, - * returning a #GFileInfo structure for each file enumerated (e.g. - * g_file_enumerate_children() will return a #GFileEnumerator for each + * `GFileEnumerator` allows you to operate on a set of [iface@Gio.File] objects, + * returning a [class@Gio.FileInfo] structure for each file enumerated (e.g. + * [method@Gio.File.enumerate_children] will return a `GFileEnumerator` for each * of the children within a directory). * - * To get the next file's information from a #GFileEnumerator, use - * g_file_enumerator_next_file() or its asynchronous version, - * g_file_enumerator_next_files_async(). Note that the asynchronous - * version will return a list of #GFileInfos, whereas the + * To get the next file's information from a `GFileEnumerator`, use + * [method@Gio.FileEnumerator.next_file] or its asynchronous version, + * [method@Gio.FileEnumerator.next_files_async]. Note that the asynchronous + * version will return a list of [class@Gio.FileInfo] objects, whereas the * synchronous will only return the next file in the enumerator. * * The ordering of returned files is unspecified for non-Unix - * platforms; for more information, see g_dir_read_name(). On Unix, + * platforms; for more information, see [method@GLib.Dir.read_name]. On Unix, * when operating on local files, returned files will be sorted by * inode number. Effectively you can assume that the ordering of * returned files will be stable between successive calls (and @@ -65,10 +63,10 @@ struct _GFileEnumeratorPrivate { * modification time, you will have to implement that in your * application code. * - * To close a #GFileEnumerator, use g_file_enumerator_close(), or - * its asynchronous version, g_file_enumerator_close_async(). Once - * a #GFileEnumerator is closed, no further actions may be performed - * on it, and it should be freed with g_object_unref(). + * To close a `GFileEnumerator`, use [method@Gio.FileEnumerator.close], or + * its asynchronous version, [method@Gio.FileEnumerator.close_async]. Once + * a `GFileEnumerator` is closed, no further actions may be performed + * on it, and it should be freed with [method@GObject.Object.unref]. * **/ diff --git a/gio/gfileenumerator.h b/gio/gfileenumerator.h index eddb58084..274d8ed15 100644 --- a/gio/gfileenumerator.h +++ b/gio/gfileenumerator.h @@ -38,11 +38,6 @@ G_BEGIN_DECLS #define G_IS_FILE_ENUMERATOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_ENUMERATOR)) #define G_FILE_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_ENUMERATOR, GFileEnumeratorClass)) -/** - * GFileEnumerator: - * - * A per matched file iterator. - **/ typedef struct _GFileEnumeratorClass GFileEnumeratorClass; typedef struct _GFileEnumeratorPrivate GFileEnumeratorPrivate; From d424383877967712507fc4b6413bf7ea409fd2c4 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:38:29 +0100 Subject: [PATCH 04/14] docs: Move the GInetAddress SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/ginetaddress.c | 28 ++++++++++------------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/gio/ginetaddress.c b/gio/ginetaddress.c index 66d889714..9d22f1b07 100644 --- a/gio/ginetaddress.c +++ b/gio/ginetaddress.c @@ -44,27 +44,19 @@ struct _GInetAddressPrivate } addr; }; -/** - * SECTION:ginetaddress - * @short_description: An IPv4/IPv6 address - * @include: gio/gio.h - * - * #GInetAddress represents an IPv4 or IPv6 internet address. Use - * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to - * look up the #GInetAddress for a hostname. Use - * g_resolver_lookup_by_address() or - * g_resolver_lookup_by_address_async() to look up the hostname for a - * #GInetAddress. - * - * To actually connect to a remote host, you will need a - * #GInetSocketAddress (which includes a #GInetAddress as well as a - * port number). - */ - /** * GInetAddress: * - * An IPv4 or IPv6 internet address. + * `GInetAddress` represents an IPv4 or IPv6 internet address. Use + * [method@Gio.Resolver.lookup_by_name] or + * [method@Gio.Resolver.lookup_by_name_async] to look up the `GInetAddress` for + * a hostname. Use [method@Gio.Resolver.lookup_by_address] or + * [method@Gio.Resolver.lookup_by_address_async] to look up the hostname for a + * `GInetAddress`. + * + * To actually connect to a remote host, you will need a + * [class@Gio.InetSocketAddress] (which includes a `GInetAddress` as well as a + * port number). */ G_DEFINE_TYPE_WITH_CODE (GInetAddress, g_inet_address, G_TYPE_OBJECT, From 55bf1883659c0847c2b269463a21fd607c3d96cd Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:38:55 +0100 Subject: [PATCH 05/14] docs: Move the GInetAddressMask SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/ginetaddressmask.c | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/gio/ginetaddressmask.c b/gio/ginetaddressmask.c index c0704db14..5831104c2 100644 --- a/gio/ginetaddressmask.c +++ b/gio/ginetaddressmask.c @@ -30,22 +30,13 @@ #include "gioenumtypes.h" #include "glibintl.h" -/** - * SECTION:ginetaddressmask - * @short_description: An IPv4/IPv6 address mask - * @include: gio/gio.h - * - * #GInetAddressMask represents a range of IPv4 or IPv6 addresses - * described by a base address and a length indicating how many bits - * of the base address are relevant for matching purposes. These are - * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10". - */ - /** * GInetAddressMask: * - * A combination of an IPv4 or IPv6 base address and a length, - * representing a range of IP addresses. + * `GInetAddressMask` represents a range of IPv4 or IPv6 addresses + * described by a base address and a length indicating how many bits + * of the base address are relevant for matching purposes. These are + * often given in string form. For example, `10.0.0.0/8`, or `fe80::/10`. * * Since: 2.32 */ From a8b28e312fb6ea4e5626558482f14b37cd5e92c9 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:39:16 +0100 Subject: [PATCH 06/14] docs: Move the GInetSocketAddress SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/ginetsocketaddress.c | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/gio/ginetsocketaddress.c b/gio/ginetsocketaddress.c index 0dee6468f..3f0b7bf90 100644 --- a/gio/ginetsocketaddress.c +++ b/gio/ginetsocketaddress.c @@ -33,20 +33,14 @@ #include "glibintl.h" -/** - * SECTION:ginetsocketaddress - * @short_description: Internet GSocketAddress - * @include: gio/gio.h - * - * An IPv4 or IPv6 socket address; that is, the combination of a - * #GInetAddress and a port number. - */ - /** * GInetSocketAddress: * - * An IPv4 or IPv6 socket address, corresponding to a struct - * sockaddr_in or struct sockaddr_in6. + * An IPv4 or IPv6 socket address. That is, the combination of a + * [class@Gio.InetAddress] and a port number. + * + * In UNIX terms, `GInetSocketAddress` corresponds to a + * [`struct sockaddr_in` or `struct sockaddr_in6`](man:sockaddr(3type)). */ struct _GInetSocketAddressPrivate From 08a16e9143da46fc10fdd0701056811c2802b5ce Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:39:36 +0100 Subject: [PATCH 07/14] docs: Move the GInputStream SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/ginputstream.c | 18 +++++++++--------- gio/ginputstream.h | 5 ----- 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/gio/ginputstream.c b/gio/ginputstream.c index e1da5face..1f27bcfb4 100644 --- a/gio/ginputstream.c +++ b/gio/ginputstream.c @@ -33,19 +33,19 @@ #include "gpollableinputstream.h" /** - * SECTION:ginputstream - * @short_description: Base class for implementing streaming input - * @include: gio/gio.h + * GInputStream: * - * #GInputStream has functions to read from a stream (g_input_stream_read()), - * to close a stream (g_input_stream_close()) and to skip some content - * (g_input_stream_skip()). + * `GInputStream` is a base class for implementing streaming input. + * + * It has functions to read from a stream ([method@Gio.InputStream.read]), + * to close a stream ([method@Gio.InputStream.close]) and to skip some content + * ([method@Gio.InputStream.skip]). * * To copy the content of an input stream to an output stream without - * manually handling the reads and writes, use g_output_stream_splice(). + * manually handling the reads and writes, use [method@Gio.OutputStream.splice]. * - * See the documentation for #GIOStream for details of thread safety of - * streaming APIs. + * See the documentation for [class@Gio.IOStream] for details of thread safety + * of streaming APIs. * * All of these functions have async variants too. **/ diff --git a/gio/ginputstream.h b/gio/ginputstream.h index a7be7689c..f5cce1708 100644 --- a/gio/ginputstream.h +++ b/gio/ginputstream.h @@ -38,11 +38,6 @@ G_BEGIN_DECLS #define G_IS_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_INPUT_STREAM)) #define G_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_INPUT_STREAM, GInputStreamClass)) -/** - * GInputStream: - * - * Base class for streaming input operations. - **/ typedef struct _GInputStreamClass GInputStreamClass; typedef struct _GInputStreamPrivate GInputStreamPrivate; From b45c554da5ec968dfa44062205c1b7dd1e2ffea6 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:39:59 +0100 Subject: [PATCH 08/14] docs: Move the GOutputStream SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/goutputstream.c | 22 +++++++++++++--------- gio/goutputstream.h | 9 --------- 2 files changed, 13 insertions(+), 18 deletions(-) diff --git a/gio/goutputstream.c b/gio/goutputstream.c index 1665e4472..e3d1ac34c 100644 --- a/gio/goutputstream.c +++ b/gio/goutputstream.c @@ -33,21 +33,25 @@ #include "gpollableoutputstream.h" /** - * SECTION:goutputstream - * @short_description: Base class for implementing streaming output - * @include: gio/gio.h + * GOutputStream: * - * #GOutputStream has functions to write to a stream (g_output_stream_write()), - * to close a stream (g_output_stream_close()) and to flush pending writes - * (g_output_stream_flush()). + * `GOutputStream` is a base class for implementing streaming output. + * + * It has functions to write to a stream ([method@Gio.OutputStream.write]), + * to close a stream ([method@Gio.OutputStream.close]) and to flush pending + * writes ([method@Gio.OutputStream.flush]). * * To copy the content of an input stream to an output stream without - * manually handling the reads and writes, use g_output_stream_splice(). + * manually handling the reads and writes, use [method@Gio.OutputStream.splice]. * - * See the documentation for #GIOStream for details of thread safety of - * streaming APIs. + * See the documentation for [class@Gio.IOStream] for details of thread safety + * of streaming APIs. * * All of these functions have async variants too. + * + * All classes derived from `GOutputStream` *should* implement synchronous + * writing, splicing, flushing and closing streams, but *may* implement + * asynchronous versions. **/ struct _GOutputStreamPrivate { diff --git a/gio/goutputstream.h b/gio/goutputstream.h index b5fafe9ef..2ee1cbb04 100644 --- a/gio/goutputstream.h +++ b/gio/goutputstream.h @@ -38,15 +38,6 @@ G_BEGIN_DECLS #define G_IS_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_OUTPUT_STREAM)) #define G_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_OUTPUT_STREAM, GOutputStreamClass)) -/** - * GOutputStream: - * - * Base class for writing output. - * - * All classes derived from GOutputStream should implement synchronous - * writing, splicing, flushing and closing streams, but may implement - * asynchronous versions. - **/ typedef struct _GOutputStreamClass GOutputStreamClass; typedef struct _GOutputStreamPrivate GOutputStreamPrivate; From c834b843b9d798ec4b3ac818777063e2dc0ab669 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:40:20 +0100 Subject: [PATCH 09/14] docs: Move the GListModel SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/glistmodel.c | 59 ++++++++++++++++++++---------------------------- 1 file changed, 25 insertions(+), 34 deletions(-) diff --git a/gio/glistmodel.c b/gio/glistmodel.c index 349b08be2..819b35374 100644 --- a/gio/glistmodel.c +++ b/gio/glistmodel.c @@ -31,74 +31,72 @@ G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT) /** - * SECTION:glistmodel - * @title: GListModel - * @short_description: An interface describing a dynamic list of objects - * @include: gio/gio.h - * @see_also: #GListStore + * GListModel: * - * #GListModel is an interface that represents a mutable list of - * #GObjects. Its main intention is as a model for various widgets in - * user interfaces, such as list views, but it can also be used as a + * `GListModel` is an interface that represents a mutable list of + * [class@GObject.Object]. Its main intention is as a model for various widgets + * in user interfaces, such as list views, but it can also be used as a * convenient method of returning lists of data, with support for * updates. * * Each object in the list may also report changes in itself via some - * mechanism (normally the #GObject::notify signal). Taken together - * with the #GListModel::items-changed signal, this provides for a list - * that can change its membership, and in which the members can change - * their individual properties. + * mechanism (normally the [signal@GObject.Object::notify] signal). Taken + * together with the [signal@Gio.ListModel::items-changed] signal, this provides + * for a list that can change its membership, and in which the members can + * change their individual properties. * * A good example would be the list of visible wireless network access * points, where each access point can report dynamic properties such as * signal strength. * - * It is important to note that the #GListModel itself does not report + * It is important to note that the `GListModel` itself does not report * changes to the individual items. It only reports changes to the list * membership. If you want to observe changes to the objects themselves * then you need to connect signals to the objects that you are * interested in. * - * All items in a #GListModel are of (or derived from) the same type. - * g_list_model_get_item_type() returns that type. The type may be an + * All items in a `GListModel` are of (or derived from) the same type. + * [method@Gio.ListModel.get_item_type] returns that type. The type may be an * interface, in which case all objects in the list must implement it. * * The semantics are close to that of an array: - * g_list_model_get_n_items() returns the number of items in the list and - * g_list_model_get_item() returns an item at a (0-based) position. In - * order to allow implementations to calculate the list length lazily, + * [method@Gio.ListModel.get_n_items] returns the number of items in the list + * and [method@Gio.ListModel.get_item] returns an item at a (0-based) position. + * In order to allow implementations to calculate the list length lazily, * you can also iterate over items: starting from 0, repeatedly call - * g_list_model_get_item() until it returns %NULL. + * [method@Gio.ListModel.get_item] until it returns `NULL`. * * An implementation may create objects lazily, but must take care to * return the same object for a given position until all references to * it are gone. * * On the other side, a consumer is expected only to hold references on - * objects that are currently "user visible", in order to facilitate the + * objects that are currently ‘user visible’, in order to facilitate the * maximum level of laziness in the implementation of the list and to * reduce the required number of signal connections at a given time. * * This interface is intended only to be used from a single thread. The * thread in which it is appropriate to use it depends on the particular * implementation, but typically it will be from the thread that owns - * the [thread-default main context][g-main-context-push-thread-default] - * in effect at the time that the model was created. + * the thread-default main context (see + * [method@GLib.MainContext.push_thread_default]) in effect at the time that the + * model was created. * - * Over time, it has established itself as good practice for listmodel + * Over time, it has established itself as good practice for list model * implementations to provide properties `item-type` and `n-items` to * ease working with them. While it is not required, it is recommended * that implementations provide these two properties. They should return - * the values of g_list_model_get_item_type() and g_list_model_get_n_items() - * respectively and be defined as such: - * |[ + * the values of [method@Gio.ListModel.get_item_type] and + * [method@Gio.ListModel.get_n_items] respectively and be defined as such: + * + * ```c * properties[PROP_ITEM_TYPE] = * g_param_spec_gtype ("item-type", "", "", G_TYPE_OBJECT, * G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); * properties[PROP_N_ITEMS] = * g_param_spec_uint ("n-items", "", "", 0, G_MAXUINT, 0, * G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); - * ]| + * ``` */ /** @@ -131,13 +129,6 @@ G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT) * Since: 2.44 */ -/** - * GListModel: - * - * #GListModel is an opaque data structure and can only be accessed - * using the following functions. - **/ - static guint g_list_model_changed_signal; static void From 49a94280c185d4f27537a6897ebb89d440ca2d2c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:40:39 +0100 Subject: [PATCH 10/14] docs: Move the GListStore SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gliststore.c | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/gio/gliststore.c b/gio/gliststore.c index 497dfb5a8..375485690 100644 --- a/gio/gliststore.c +++ b/gio/gliststore.c @@ -28,25 +28,15 @@ #include "glistmodel.h" /** - * SECTION:gliststore - * @title: GListStore - * @short_description: A simple implementation of #GListModel - * @include: gio/gio.h + * GListStore: * - * #GListStore is a simple implementation of #GListModel that stores all - * items in memory. + * `GListStore` is a simple implementation of [iface@Gio.ListModel] that stores + * all items in memory. * * It provides insertions, deletions, and lookups in logarithmic time * with a fast path for the common case of iterating the list linearly. */ -/** - * GListStore: - * - * #GListStore is an opaque data structure and can only be accessed - * using the following functions. - **/ - struct _GListStore { GObject parent_instance; From 47da98d7f796cf641a027fca5c07aecc33546196 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:41:01 +0100 Subject: [PATCH 11/14] docs: Move the GMenu SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gmenu.c | 26 ++++++++------------------ 1 file changed, 8 insertions(+), 18 deletions(-) diff --git a/gio/gmenu.c b/gio/gmenu.c index adef4cc15..dd4daeeca 100644 --- a/gio/gmenu.c +++ b/gio/gmenu.c @@ -28,27 +28,17 @@ #include "gicon.h" -/** - * SECTION:gmenu - * @title: GMenu - * @short_description: A simple implementation of GMenuModel - * @include: gio/gio.h - * - * #GMenu is a simple implementation of #GMenuModel. - * You populate a #GMenu by adding #GMenuItem instances to it. - * - * There are some convenience functions to allow you to directly - * add items (avoiding #GMenuItem) for the common cases. To add - * a regular item, use g_menu_insert(). To add a section, use - * g_menu_insert_section(). To add a submenu, use - * g_menu_insert_submenu(). - */ - /** * GMenu: * - * #GMenu is an opaque structure type. You must access it using the - * functions below. + * `GMenu` is a simple implementation of [class@Gio.MenuModel]. + * You populate a `GMenu` by adding [class@Gio.MenuItem] instances to it. + * + * There are some convenience functions to allow you to directly + * add items (avoiding [class@Gio.MenuItem]) for the common cases. To add + * a regular item, use [method@Gio.Menu.insert]. To add a section, use + * [method@Gio.Menu.insert_section]. To add a submenu, use + * [method@Gio.Menu.insert_submenu]. * * Since: 2.32 */ From f17cb81ce52ea8628686086dda5cb2a0b9a43aa2 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:41:19 +0100 Subject: [PATCH 12/14] docs: Move the GMountOperation SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gmountoperation.c | 20 +++++++++----------- gio/gmountoperation.h | 6 ------ 2 files changed, 9 insertions(+), 17 deletions(-) diff --git a/gio/gmountoperation.c b/gio/gmountoperation.c index d8f54493f..6153498cc 100644 --- a/gio/gmountoperation.c +++ b/gio/gmountoperation.c @@ -31,27 +31,25 @@ /** - * SECTION:gmountoperation - * @short_description: Object used for authentication and user interaction - * @include: gio/gio.h + * GMountOperation: * - * #GMountOperation provides a mechanism for interacting with the user. + * `GMountOperation` provides a mechanism for interacting with the user. * It can be used for authenticating mountable operations, such as loop * mounting files, hard drive partitions or server locations. It can * also be used to ask the user questions or show a list of applications * preventing unmount or eject operations from completing. * - * Note that #GMountOperation is used for more than just #GMount - * objects – for example it is also used in g_drive_start() and - * g_drive_stop(). + * Note that `GMountOperation` is used for more than just [iface@Gio.Mount] + * objects – for example it is also used in [method@Gio.Drive.start] and + * [method@Gio.Drive.stop]. * * Users should instantiate a subclass of this that implements all the * various callbacks to show the required dialogs, such as - * #GtkMountOperation. If no user interaction is desired (for example - * when automounting filesystems at login time), usually %NULL can be - * passed, see each method taking a #GMountOperation for details. + * [class@Gtk.MountOperation]. If no user interaction is desired (for example + * when automounting filesystems at login time), usually `NULL` can be + * passed, see each method taking a `GMountOperation` for details. * - * The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. + * Throughout the API, the term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. * [TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for * encrypting file containers, partitions or whole disks, typically used with Windows. * [VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various diff --git a/gio/gmountoperation.h b/gio/gmountoperation.h index b763f0d6a..3302ec567 100644 --- a/gio/gmountoperation.h +++ b/gio/gmountoperation.h @@ -38,12 +38,6 @@ G_BEGIN_DECLS #define G_IS_MOUNT_OPERATION_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MOUNT_OPERATION)) #define G_MOUNT_OPERATION_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MOUNT_OPERATION, GMountOperationClass)) -/** - * GMountOperation: - * - * Class for providing authentication methods for mounting operations, - * such as mounting a file locally, or authenticating with a server. - **/ typedef struct _GMountOperationClass GMountOperationClass; typedef struct _GMountOperationPrivate GMountOperationPrivate; From cf7fd070c8169c047804d1a11ace8ddada9eeb82 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:41:44 +0100 Subject: [PATCH 13/14] docs: Move the GNativeSocketAddress SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gnativesocketaddress.c | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/gio/gnativesocketaddress.c b/gio/gnativesocketaddress.c index 28b90a801..c2c47a1fe 100644 --- a/gio/gnativesocketaddress.c +++ b/gio/gnativesocketaddress.c @@ -31,19 +31,15 @@ #include "glibintl.h" -/** - * SECTION:gnativesocketaddress - * @short_description: Native GSocketAddress - * @include: gio/gio.h - * - * A socket address of some unknown native type. - */ - /** * GNativeSocketAddress: * - * A socket address, corresponding to a general struct - * sockadd address of a type not otherwise handled by glib. + * A socket address of some unknown native type. + * + * This corresponds to a general `struct sockaddr` of a type not otherwise + * handled by GLib. + * + * Since: 2.46 */ struct _GNativeSocketAddressPrivate From 1c2207d9fb606282dc7aed82937ac440b4d37c8f Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 14:42:05 +0100 Subject: [PATCH 14/14] docs: Move the GOsxAppInfo SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gosxappinfo.m | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/gio/gosxappinfo.m b/gio/gosxappinfo.m index 60b088641..50b08e0be 100644 --- a/gio/gosxappinfo.m +++ b/gio/gosxappinfo.m @@ -33,12 +33,10 @@ #import /** - * SECTION:gosxappinfo - * @title: GOsxAppInfo - * @short_description: Application information from NSBundles - * @include: gio/gosxappinfo.h + * GOsxAppInfo: * - * #GOsxAppInfo is an implementation of #GAppInfo based on NSBundle information. + * `GOsxAppInfo` is an implementation of [iface@Gio.AppInfo] based on `NSBundle` + * information. * * Note that `` is unique to OSX. */ @@ -46,11 +44,6 @@ static void g_osx_app_info_iface_init (GAppInfoIface *iface); static const char *g_osx_app_info_get_id (GAppInfo *appinfo); -/** - * GOsxAppInfo: - * - * Information about an installed application from a NSBundle. - */ struct _GOsxAppInfo { GObject parent_instance;