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

Switch to using gi-docgen for docs (batch 6)

See merge request GNOME/glib!3661

gio/gdebugcontrollerdbus.c

@@ -31,35 +31,34 @@
 #include "gio/gmarshal-internal.h"
 
 /**
- * SECTION:gdebugcontrollerdbus
+ * GDebugControllerDBus:
- * @title: GDebugControllerDBus
- * @short_description: Debugging controller D-Bus implementation
- * @include: gio/gio.h
  *
- * #GDebugControllerDBus is an implementation of #GDebugController which exposes
+ * `GDebugControllerDBus` is an implementation of [iface@Gio.DebugController]
- * debug settings as a D-Bus object.
+ * 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
+ * [property@Gio.DebugControllerDBus:connection] once it’s initialized. The
- * unregistered when the last reference to the #GDebugControllerDBus is dropped.
+ * 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().
+ * [property@Gio.DebugController:debug-enabled] and, by default,
- * 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
+ * [signal@Gio.DebugControllerDBus::authorize] signal handler is installed. This
- * the process may be privileged, or might expose sensitive information in its
+ * is because the process may be privileged, or might expose sensitive
- * debug output. You may want to restrict the ability to enable debug output to
+ * information in its debug output. You may want to restrict the ability to
- * privileged users or processes.
+ * 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/`:
- * |[<!-- language="XML" -->
+ *
+ * ```xml
  * <?xml version="1.0"?> <!--*-nxml-*-->
  * <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
  *      "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
@@ -71,7 +70,7 @@
  *     <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
  *   </policy>
  * </busconfig>
- * ]|
+ * ```
  *
  * 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
+ * connect to the [signal@Gio.DebugControllerDBus::authorize] signal and query
- * it:
+ * polkit in it:
- * |[<!-- language="C" -->
+ *
+ * ```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
  */

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)

gio/gfiledescriptorbased.c

@@ -26,20 +26,18 @@
 
 
 /**
- * SECTION:gfiledescriptorbased
+ * GFileDescriptorBased:
- * @short_description: Interface for file descriptor based IO
- * @include: gio/gfiledescriptorbased.h
- * @see_also: #GInputStream, #GOutputStream
  *
- * #GFileDescriptorBased is implemented by streams (implementations of
+ * `GFileDescriptorBased` is an interface for file descriptor based IO.
- * #GInputStream or #GOutputStream) that are based on file descriptors.
+ *
+ * It is implemented by streams (implementations of [class@Gio.InputStream] or
+ * [class@Gio.OutputStream]) that are based on file descriptors.
  *
  * Note that `<gio/gfiledescriptorbased.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.
  *
  * Since: 2.24
- *
  **/
 
 typedef GFileDescriptorBasedIface GFileDescriptorBasedInterface;

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

gio/gfileenumerator.c

@@ -39,23 +39,21 @@ struct _GFileEnumeratorPrivate {
 };
 
 /**
- * SECTION:gfileenumerator
+ * GFileEnumerator:
- * @short_description: Enumerated Files Routines
- * @include: gio/gio.h
  * 
- * #GFileEnumerator allows you to operate on a set of #GFiles, 
+ * `GFileEnumerator` allows you to operate on a set of [iface@Gio.File] objects,
- * returning a #GFileInfo structure for each file enumerated (e.g. 
+ * returning a [class@Gio.FileInfo] structure for each file enumerated (e.g.
- * g_file_enumerate_children() will return a #GFileEnumerator for each 
+ * [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 
+ * To get the next file's information from a `GFileEnumerator`, use
- * g_file_enumerator_next_file() or its asynchronous version, 
+ * [method@Gio.FileEnumerator.next_file] or its asynchronous version,
- * g_file_enumerator_next_files_async(). Note that the asynchronous 
+ * [method@Gio.FileEnumerator.next_files_async]. Note that the asynchronous
- * version will return a list of #GFileInfos, whereas the 
+ * 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 
+ * To close a `GFileEnumerator`, use [method@Gio.FileEnumerator.close], or
- * its asynchronous version, g_file_enumerator_close_async(). Once 
+ * its asynchronous version, [method@Gio.FileEnumerator.close_async]. Once
- * a #GFileEnumerator is closed, no further actions may be performed 
+ * a `GFileEnumerator` is closed, no further actions may be performed
- * on it, and it should be freed with g_object_unref().
+ * on it, and it should be freed with [method@GObject.Object.unref].
  * 
  **/ 
 

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;
 

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,

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,
+ * `GInetAddressMask` represents a range of IPv4 or IPv6 addresses
- * representing a range of IP 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
  */

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
+ * An IPv4 or IPv6 socket address. That is, the combination of a
- * sockaddr_in or struct sockaddr_in6.
+ * [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

gio/ginputstream.c

@@ -33,19 +33,19 @@
 #include "gpollableinputstream.h"
 
 /**
- * SECTION:ginputstream
+ * GInputStream:
- * @short_description: Base class for implementing streaming input
- * @include: gio/gio.h
  *
- * #GInputStream has functions to read from a stream (g_input_stream_read()),
+ * `GInputStream` is a base class for implementing streaming input.
- * to close a stream (g_input_stream_close()) and to skip some content
+ *
- * (g_input_stream_skip()). 
+ * 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
+ * See the documentation for [class@Gio.IOStream] for details of thread safety
- * streaming APIs.
+ * of streaming APIs.
  *
  * All of these functions have async variants too.
  **/

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;
 

gio/glistmodel.c

@@ -31,74 +31,72 @@
 G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT)
 
 /**
- * SECTION:glistmodel
+ * GListModel:
- * @title: GListModel
- * @short_description: An interface describing a dynamic list of objects
- * @include: gio/gio.h
- * @see_also: #GListStore
  *
- * #GListModel is an interface that represents a mutable list of
+ * `GListModel` is an interface that represents a mutable list of
- * #GObjects. Its main intention is as a model for various widgets in
+ * [class@GObject.Object]. Its main intention is as a model for various widgets
- * user interfaces, such as list views, but it can also be used as a
+ * 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
+ * mechanism (normally the [signal@GObject.Object::notify] signal).  Taken
- * with the #GListModel::items-changed signal, this provides for a list
+ * together with the [signal@Gio.ListModel::items-changed] signal, this provides
- * that can change its membership, and in which the members can change
+ * for a list that can change its membership, and in which the members can
- * their individual properties.
+ * 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.
+ * 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
+ * [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
+ * [method@Gio.ListModel.get_n_items] returns the number of items in the list
- * g_list_model_get_item() returns an item at a (0-based) position. In
+ * and [method@Gio.ListModel.get_item] returns an item at a (0-based) position.
- * order to allow implementations to calculate the list length lazily,
+ * 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]
+ * the thread-default main context (see
- * in effect at the time that the model was created.
+ * [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()
+ * the values of [method@Gio.ListModel.get_item_type] and
- * respectively and be defined as such:
+ * [method@Gio.ListModel.get_n_items] respectively and be defined as such:
- * |[<!-- language="C" -->
+ *
+ * ```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

gio/gliststore.c

@@ -28,25 +28,15 @@
 #include "glistmodel.h"
 
 /**
- * SECTION:gliststore
+ * GListStore:
- * @title: GListStore
- * @short_description: A simple implementation of #GListModel
- * @include: gio/gio.h
  *
- * #GListStore is a simple implementation of #GListModel that stores all
+ * `GListStore` is a simple implementation of [iface@Gio.ListModel] that stores
- * items in memory.
+ * 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;

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
+ * `GMenu` is a simple implementation of [class@Gio.MenuModel].
- * functions below.
+ * 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
  */

gio/gmountoperation.c

@@ -31,27 +31,25 @@
 
 
 /**
- * SECTION:gmountoperation
+ * GMountOperation:
- * @short_description: Object used for authentication and user interaction
- * @include: gio/gio.h
  *
- * #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
+ * Note that `GMountOperation` is used for more than just [iface@Gio.Mount]
- * objects – for example it is also used in g_drive_start() and
+ * objects – for example it is also used in [method@Gio.Drive.start] and
- * g_drive_stop().
+ * [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
+ * [class@Gtk.MountOperation]. If no user interaction is desired (for example
- * when automounting filesystems at login time), usually %NULL can be
+ * when automounting filesystems at login time), usually `NULL` can be
- * passed, see each method taking a #GMountOperation for details.
+ * 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

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;
 

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
+ * A socket address of some unknown native type.
- * sockadd address of a type not otherwise handled by glib.
+ *
+ * This corresponds to a general `struct sockaddr` of a type not otherwise
+ * handled by GLib.
+ *
+ * Since: 2.46
  */
 
 struct _GNativeSocketAddressPrivate

gio/gosxappinfo.m

@@ -33,12 +33,10 @@
 #import <ApplicationServices/ApplicationServices.h>
 
 /**
- * SECTION:gosxappinfo
+ * GOsxAppInfo:
- * @title: GOsxAppInfo
- * @short_description: Application information from NSBundles
- * @include: gio/gosxappinfo.h
  *
- * #GOsxAppInfo is an implementation of #GAppInfo based on NSBundle information.
+ * `GOsxAppInfo` is an implementation of [iface@Gio.AppInfo] based on `NSBundle`
+ * information.
  *
  * Note that `<gio/gosxappinfo.h>` 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;

gio/goutputstream.c

@@ -33,21 +33,25 @@
 #include "gpollableoutputstream.h"
 
 /**
- * SECTION:goutputstream
+ * GOutputStream:
- * @short_description: Base class for implementing streaming output
- * @include: gio/gio.h
  *
- * #GOutputStream has functions to write to a stream (g_output_stream_write()),
+ * `GOutputStream` is a base class for implementing streaming output.
- * to close a stream (g_output_stream_close()) and to flush pending writes
+ *
- * (g_output_stream_flush()). 
+ * 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
+ * See the documentation for [class@Gio.IOStream] for details of thread safety
- * streaming APIs.
+ * 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 {

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;