From 2f010f5618345a8bb81ad91f432fedeb122ec1bc Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 20 Dec 2024 12:25:22 +0000 Subject: [PATCH 1/5] gunixmounts: Fix typo in deprecation documentation Signed-off-by: Philip Withnall --- gio/gunixmounts.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c index 499123548..57ebb93e1 100644 --- a/gio/gunixmounts.c +++ b/gio/gunixmounts.c @@ -2187,7 +2187,7 @@ g_unix_mount_point_at (const char *mount_path, * * Returns: %TRUE if the mounts have changed since @time. * - * Deprecated: 2.84: Use g_unix_mount_entry_free() instead. + * Deprecated: 2.84: Use g_unix_mount_entries_changed_since() instead. **/ gboolean g_unix_mounts_changed_since (guint64 time) From 05afb30510fb98d8a564759556d11f7a1037df5a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 20 Dec 2024 12:34:12 +0000 Subject: [PATCH 2/5] gunixmounts: Document caveats with *_changed_since() APIs They need a `GUnixMountMonitor` to give valid timestamps, and if you have one of those then you might as well listen to its signals anyway. Signed-off-by: Philip Withnall Fixes: #3569 --- gio/gunixmounts.c | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c index 57ebb93e1..a62508047 100644 --- a/gio/gunixmounts.c +++ b/gio/gunixmounts.c @@ -2201,6 +2201,16 @@ g_unix_mounts_changed_since (guint64 time) * * Checks if the unix mounts have changed since a given unix time. * + * This can only work reliably if a [class@GioUnix.MountMonitor] is running in + * the process, otherwise changes in the mount entries file (such as + * `/proc/self/mountinfo` on Linux) cannot be detected and, as a result, this + * function has to conservatively always return `TRUE`. + * + * It is more efficient to use [signal@GioUnix.MountMonitor::mounts-changed] to + * be signalled of changes to the mount entries, rather than polling using this + * function. This function is more appropriate for infrequently determining + * cache validity. + * * Returns: %TRUE if the mounts have changed since @time. * Since 2.84 **/ @@ -2216,6 +2226,16 @@ g_unix_mount_entries_changed_since (guint64 time) * * Checks if the unix mount points have changed since a given unix time. * + * Unlike [func@GioUnix.mount_entries_changed_since], this function can work + * reliably without a [class@GioUnix.MountMonitor] running, as it accesses the + * static mount point information (such as `/etc/fstab` on Linux), which has a + * valid modification time. + * + * It is more efficient to use [signal@GioUnix.MountMonitor::mountpoints-changed] + * to be signalled of changes to the mount points, rather than polling using + * this function. This function is more appropriate for infrequently determining + * cache validity. + * * Returns: %TRUE if the mount points have changed since @time. **/ gboolean From 12f969eb7965f4b51e6e17a9592e7f1ad2ac2420 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 20 Dec 2024 12:42:58 +0000 Subject: [PATCH 3/5] gunixmounts: Consistently capitalise Unix in the documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Let’s not go with SHOUTY UNIX or quiet unix, let’s just call it what Wikipedia calls it (https://en.wikipedia.org/wiki/Unix). Signed-off-by: Philip Withnall --- gio/gunixmounts.c | 122 +++++++++++++++++++++++----------------------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c index a62508047..c68d55c98 100644 --- a/gio/gunixmounts.c +++ b/gio/gunixmounts.c @@ -89,21 +89,21 @@ static const char *_resolve_dev_root (void); /** * GUnixMountType: - * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type. - * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type. - * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type. - * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type. - * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type. - * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type. - * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type. - * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type. - * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type. - * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type. - * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type. - * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type. - * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type. + * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown Unix mount type. + * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk Unix mount type. + * @G_UNIX_MOUNT_TYPE_CDROM: CDROM Unix mount type. + * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) Unix mount type. + * @G_UNIX_MOUNT_TYPE_ZIP: ZIP Unix mount type. + * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ Unix mount type. + * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick Unix mount type. + * @G_UNIX_MOUNT_TYPE_CF: Compact Flash Unix mount type. + * @G_UNIX_MOUNT_TYPE_SM: Smart Media Unix mount type. + * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC Unix mount type. + * @G_UNIX_MOUNT_TYPE_IPOD: iPod Unix mount type. + * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera Unix mount type. + * @G_UNIX_MOUNT_TYPE_HD: Hard drive Unix mount type. * - * Types of UNIX mounts. + * Types of Unix mounts. **/ typedef enum { G_UNIX_MOUNT_TYPE_UNKNOWN, @@ -1808,13 +1808,13 @@ get_mount_points_timestamp (void) * g_unix_mounts_get: * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL * - * Gets a #GList of #GUnixMountEntry containing the unix mounts. + * Gets a #GList of #GUnixMountEntry containing the Unix mounts. * If @time_read is set, it will be filled with the mount * timestamp, allowing for checking if the mounts have changed * with g_unix_mount_entries_changed_since(). * * Returns: (element-type GUnixMountEntry) (transfer full): - * a #GList of the UNIX mounts. + * a #GList of the Unix mounts. * * Deprecated: 2.84: Use g_unix_mount_entries_get() instead. */ @@ -1828,13 +1828,13 @@ g_unix_mounts_get (guint64 *time_read) * g_unix_mount_entries_get: * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL * - * Gets a #GList of #GUnixMountEntry containing the unix mounts. + * Gets a #GList of #GUnixMountEntry containing the Unix mounts. * If @time_read is set, it will be filled with the mount * timestamp, allowing for checking if the mounts have changed * with g_unix_mount_entries_changed_since(). * * Returns: (element-type GUnixMountEntry) (transfer full): - * a #GList of the UNIX mounts. + * a #GList of the Unix mounts. * * Since: 2.84 */ @@ -1914,11 +1914,11 @@ g_unix_mount_entries_get_from_file (const char *table_path, /** * g_unix_mount_at: - * @mount_path: (type filename): path for a possible unix mount. + * @mount_path: (type filename): path for a possible Unix mount. * @time_read: (out) (optional): guint64 to contain a timestamp. * * Gets a #GUnixMountEntry for a given mount path. If @time_read - * is set, it will be filled with a unix timestamp for checking + * is set, it will be filled with a Unix timestamp for checking * if the mounts have changed since with g_unix_mount_entries_changed_since(). * * If more mounts have the same mount path, the last matching mount @@ -1939,11 +1939,11 @@ g_unix_mount_at (const char *mount_path, /** * g_unix_mount_entry_at: - * @mount_path: (type filename): path for a possible unix mount. + * @mount_path: (type filename): path for a possible Unix mount. * @time_read: (out) (optional): guint64 to contain a timestamp. * * Gets a #GUnixMountEntry for a given mount path. If @time_read - * is set, it will be filled with a unix timestamp for checking + * is set, it will be filled with a Unix timestamp for checking * if the mounts have changed since with g_unix_mount_entries_changed_since(). * * If more mounts have the same mount path, the last matching mount @@ -1986,11 +1986,11 @@ g_unix_mount_entry_at (const char *mount_path, /** * g_unix_mount_for: - * @file_path: (type filename): file path on some unix mount. + * @file_path: (type filename): file path on some Unix mount. * @time_read: (out) (optional): guint64 to contain a timestamp. * * Gets a #GUnixMountEntry for a given file path. If @time_read - * is set, it will be filled with a unix timestamp for checking + * is set, it will be filled with a Unix timestamp for checking * if the mounts have changed since with g_unix_mount_entries_changed_since(). * * If more mounts have the same mount path, the last matching mount @@ -2013,11 +2013,11 @@ g_unix_mount_for (const char *file_path, /** * g_unix_mount_entry_for: - * @file_path: (type filename): file path on some unix mount. + * @file_path: (type filename): file path on some Unix mount. * @time_read: (out) (optional): guint64 to contain a timestamp. * * Gets a #GUnixMountEntry for a given file path. If @time_read - * is set, it will be filled with a unix timestamp for checking + * is set, it will be filled with a Unix timestamp for checking * if the mounts have changed since with g_unix_mount_entries_changed_since(). * * If more mounts have the same mount path, the last matching mount @@ -2066,13 +2066,13 @@ copy_mount_point_cb (gconstpointer src, * g_unix_mount_points_get: * @time_read: (out) (optional): guint64 to contain a timestamp. * - * Gets a #GList of #GUnixMountPoint containing the unix mount points. + * Gets a #GList of #GUnixMountPoint containing the Unix mount points. * If @time_read is set, it will be filled with the mount timestamp, * allowing for checking if the mounts have changed with * g_unix_mount_points_changed_since(). * * Returns: (element-type GUnixMountPoint) (transfer full): - * a #GList of the UNIX mountpoints. + * a #GList of the Unix mountpoints. **/ GList * g_unix_mount_points_get (guint64 *time_read) @@ -2135,11 +2135,11 @@ g_unix_mount_points_get_from_file (const char *table_path, /** * g_unix_mount_point_at: - * @mount_path: (type filename): path for a possible unix mount point. + * @mount_path: (type filename): path for a possible Unix mount point. * @time_read: (out) (optional): guint64 to contain a timestamp. * * Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it - * will be filled with a unix timestamp for checking if the mount points have + * will be filled with a Unix timestamp for checking if the mount points have * changed since with g_unix_mount_points_changed_since(). * * If more mount points have the same mount path, the last matching mount point @@ -2183,7 +2183,7 @@ g_unix_mount_point_at (const char *mount_path, * g_unix_mounts_changed_since: * @time: guint64 to contain a timestamp. * - * Checks if the unix mounts have changed since a given unix time. + * Checks if the Unix mounts have changed since a given Unix time. * * Returns: %TRUE if the mounts have changed since @time. * @@ -2199,7 +2199,7 @@ g_unix_mounts_changed_since (guint64 time) * g_unix_mount_entries_changed_since: * @time: guint64 to contain a timestamp. * - * Checks if the unix mounts have changed since a given unix time. + * Checks if the Unix mounts have changed since a given Unix time. * * This can only work reliably if a [class@GioUnix.MountMonitor] is running in * the process, otherwise changes in the mount entries file (such as @@ -2224,7 +2224,7 @@ g_unix_mount_entries_changed_since (guint64 time) * g_unix_mount_points_changed_since: * @time: guint64 to contain a timestamp. * - * Checks if the unix mount points have changed since a given unix time. + * Checks if the Unix mount points have changed since a given Unix time. * * Unlike [func@GioUnix.mount_entries_changed_since], this function can work * reliably without a [class@GioUnix.MountMonitor] running, as it accesses the @@ -2603,7 +2603,7 @@ g_unix_mount_monitor_class_init (GUnixMountMonitorClass *klass) * GUnixMountMonitor::mounts-changed: * @monitor: the object on which the signal is emitted * - * Emitted when the unix mounts have changed. + * Emitted when the Unix mounts have changed. */ signals[MOUNTS_CHANGED] = g_signal_new (I_("mounts-changed"), @@ -2618,7 +2618,7 @@ g_unix_mount_monitor_class_init (GUnixMountMonitorClass *klass) * GUnixMountMonitor::mountpoints-changed: * @monitor: the object on which the signal is emitted * - * Emitted when the unix mount points have changed. + * Emitted when the Unix mount points have changed. */ signals[MOUNTPOINTS_CHANGED] = g_signal_new (I_("mountpoints-changed"), @@ -2708,7 +2708,7 @@ g_unix_mount_monitor_new (void) * g_unix_mount_free: * @mount_entry: a #GUnixMountEntry. * - * Frees a unix mount. + * Frees a Unix mount. * * Deprecated: 2.84: Use g_unix_mount_entry_free() instead. */ @@ -2722,7 +2722,7 @@ g_unix_mount_free (GUnixMountEntry *mount_entry) * g_unix_mount_entry_free: * @mount_entry: a #GUnixMountEntry. * - * Frees a unix mount. + * Frees a Unix mount. * * Since: 2.84 */ @@ -2787,9 +2787,9 @@ g_unix_mount_entry_copy (GUnixMountEntry *mount_entry) /** * g_unix_mount_point_free: - * @mount_point: unix mount point to free. + * @mount_point: Unix mount point to free. * - * Frees a unix mount point. + * Frees a Unix mount point. */ void g_unix_mount_point_free (GUnixMountPoint *mount_point) @@ -2837,7 +2837,7 @@ g_unix_mount_point_copy (GUnixMountPoint *mount_point) * @mount1: first #GUnixMountEntry to compare. * @mount2: second #GUnixMountEntry to compare. * - * Compares two unix mounts. + * Compares two Unix mounts. * * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, * or less than @mount2, respectively. @@ -2856,7 +2856,7 @@ g_unix_mount_compare (GUnixMountEntry *mount1, * @mount1: first #GUnixMountEntry to compare. * @mount2: second #GUnixMountEntry to compare. * - * Compares two unix mounts. + * Compares two Unix mounts. * * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, * or less than @mount2, respectively. @@ -2902,7 +2902,7 @@ g_unix_mount_entry_compare (GUnixMountEntry *mount1, * g_unix_mount_get_mount_path: * @mount_entry: input #GUnixMountEntry to get the mount path for. * - * Gets the mount path for a unix mount. + * Gets the mount path for a Unix mount. * * Returns: (type filename): the mount path for @mount_entry. * @@ -2918,7 +2918,7 @@ g_unix_mount_get_mount_path (GUnixMountEntry *mount_entry) * g_unix_mount_entry_get_mount_path: * @mount_entry: input #GUnixMountEntry to get the mount path for. * - * Gets the mount path for a unix mount. + * Gets the mount path for a Unix mount. * * Returns: (type filename): the mount path for @mount_entry. * @@ -2936,7 +2936,7 @@ g_unix_mount_entry_get_mount_path (GUnixMountEntry *mount_entry) * g_unix_mount_get_device_path: * @mount_entry: a #GUnixMount. * - * Gets the device path for a unix mount. + * Gets the device path for a Unix mount. * * Returns: (type filename): a string containing the device path. * @@ -2952,7 +2952,7 @@ g_unix_mount_get_device_path (GUnixMountEntry *mount_entry) * g_unix_mount_entry_get_device_path: * @mount_entry: a #GUnixMount. * - * Gets the device path for a unix mount. + * Gets the device path for a Unix mount. * * Returns: (type filename): a string containing the device path. * @@ -3015,7 +3015,7 @@ g_unix_mount_entry_get_root_path (GUnixMountEntry *mount_entry) * g_unix_mount_get_fs_type: * @mount_entry: a #GUnixMount. * - * Gets the filesystem type for the unix mount. + * Gets the filesystem type for the Unix mount. * * Returns: a string containing the file system type. * @@ -3031,7 +3031,7 @@ g_unix_mount_get_fs_type (GUnixMountEntry *mount_entry) * g_unix_mount_entry_get_fs_type: * @mount_entry: a #GUnixMount. * - * Gets the filesystem type for the unix mount. + * Gets the filesystem type for the Unix mount. * * Returns: a string containing the file system type. * @@ -3049,7 +3049,7 @@ g_unix_mount_entry_get_fs_type (GUnixMountEntry *mount_entry) * g_unix_mount_get_options: * @mount_entry: a #GUnixMountEntry. * - * Gets a comma-separated list of mount options for the unix mount. For example, + * Gets a comma-separated list of mount options for the Unix mount. For example, * `rw,relatime,seclabel,data=ordered`. * * This is similar to g_unix_mount_point_get_options(), but it takes @@ -3071,7 +3071,7 @@ g_unix_mount_get_options (GUnixMountEntry *mount_entry) * g_unix_mount_entry_get_options: * @mount_entry: a #GUnixMountEntry. * - * Gets a comma-separated list of mount options for the unix mount. For example, + * Gets a comma-separated list of mount options for the Unix mount. For example, * `rw,relatime,seclabel,data=ordered`. * * This is similar to g_unix_mount_point_get_options(), but it takes @@ -3094,7 +3094,7 @@ g_unix_mount_entry_get_options (GUnixMountEntry *mount_entry) * g_unix_mount_is_readonly: * @mount_entry: a #GUnixMount. * - * Checks if a unix mount is mounted read only. + * Checks if a Unix mount is mounted read only. * * Returns: %TRUE if @mount_entry is read only. * @@ -3110,7 +3110,7 @@ g_unix_mount_is_readonly (GUnixMountEntry *mount_entry) * g_unix_mount_entry_is_readonly: * @mount_entry: a #GUnixMount. * - * Checks if a unix mount is mounted read only. + * Checks if a Unix mount is mounted read only. * * Returns: %TRUE if @mount_entry is read only. * @@ -3135,7 +3135,7 @@ g_unix_mount_entry_is_readonly (GUnixMountEntry *mount_entry) * The definition of what a ‘system’ mount entry is may change over time as new * file system types and device paths are ignored. * - * Returns: %TRUE if the unix mount is for a system path. + * Returns: %TRUE if the Unix mount is for a system path. * * Deprecated: 2.84: Use g_unix_mount_entry_is_system_internal() instead. */ @@ -3156,7 +3156,7 @@ g_unix_mount_is_system_internal (GUnixMountEntry *mount_entry) * The definition of what a ‘system’ mount entry is may change over time as new * file system types and device paths are ignored. * - * Returns: %TRUE if the unix mount is for a system path. + * Returns: %TRUE if the Unix mount is for a system path. * * Since: 2.84 */ @@ -3174,7 +3174,7 @@ g_unix_mount_entry_is_system_internal (GUnixMountEntry *mount_entry) * @mount1: a #GUnixMount. * @mount2: a #GUnixMount. * - * Compares two unix mount points. + * Compares two Unix mount points. * * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, * or less than @mount2, respectively. @@ -3222,7 +3222,7 @@ g_unix_mount_point_compare (GUnixMountPoint *mount1, * g_unix_mount_point_get_mount_path: * @mount_point: a #GUnixMountPoint. * - * Gets the mount path for a unix mount point. + * Gets the mount path for a Unix mount point. * * Returns: (type filename): a string containing the mount path. */ @@ -3238,7 +3238,7 @@ g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point) * g_unix_mount_point_get_device_path: * @mount_point: a #GUnixMountPoint. * - * Gets the device path for a unix mount point. + * Gets the device path for a Unix mount point. * * Returns: (type filename): a string containing the device path. */ @@ -3288,7 +3288,7 @@ g_unix_mount_point_get_options (GUnixMountPoint *mount_point) * g_unix_mount_point_is_readonly: * @mount_point: a #GUnixMountPoint. * - * Checks if a unix mount point is read only. + * Checks if a Unix mount point is read only. * * Returns: %TRUE if a mount point is read only. */ @@ -3304,7 +3304,7 @@ g_unix_mount_point_is_readonly (GUnixMountPoint *mount_point) * g_unix_mount_point_is_user_mountable: * @mount_point: a #GUnixMountPoint. * - * Checks if a unix mount point is mountable by the user. + * Checks if a Unix mount point is mountable by the user. * * Returns: %TRUE if the mount point is user mountable. */ @@ -3320,7 +3320,7 @@ g_unix_mount_point_is_user_mountable (GUnixMountPoint *mount_point) * g_unix_mount_point_is_loopback: * @mount_point: a #GUnixMountPoint. * - * Checks if a unix mount point is a loopback device. + * Checks if a Unix mount point is a loopback device. * * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. */ @@ -3416,7 +3416,7 @@ guess_mount_type (const char *mount_path, * g_unix_mount_entry_guess_type: * @mount_entry: a #GUnixMount. * - * Guesses the type of a unix mount. If the mount type cannot be + * Guesses the type of a Unix mount. If the mount type cannot be * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. * * Returns: a #GUnixMountType. @@ -3438,7 +3438,7 @@ g_unix_mount_entry_guess_type (GUnixMountEntry *mount_entry) * g_unix_mount_point_guess_type: * @mount_point: a #GUnixMountPoint. * - * Guesses the type of a unix mount point. + * Guesses the type of a Unix mount point. * If the mount type cannot be determined, * returns %G_UNIX_MOUNT_TYPE_UNKNOWN. * From 46160f9aad32c8a32b38c8e6dd7ecc4bc992f1c6 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 20 Dec 2024 15:11:41 +0000 Subject: [PATCH 4/5] gunixmounts: Convert docs to gi-docgen linking syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Improve formatting while I’m there, and try and ensure all the docs in these two files matches the [guidelines](https://developer.gnome.org/documentation/guidelines/devel-docs.html#writing-api-references). Signed-off-by: Philip Withnall Helps: #3250 --- gio/gunixmounts.c | 576 +++++++++++++++++++++++----------------------- gio/gunixmounts.h | 9 +- 2 files changed, 290 insertions(+), 295 deletions(-) diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c index c68d55c98..7ab0daf4d 100644 --- a/gio/gunixmounts.c +++ b/gio/gunixmounts.c @@ -270,12 +270,14 @@ unix_mount_point_array_free_to_list (GUnixMountPoint **points, * @mount_path: (type filename): a mount path, e.g. `/media/disk` or `/usr` * * Determines if @mount_path is considered an implementation of the - * OS. This is primarily used for hiding mountable and mounted volumes + * OS. + * + * This is primarily used for hiding mountable and mounted volumes * that only are used in the OS and has little to no relevance to the * casual user. * - * Returns: %TRUE if @mount_path is considered an implementation detail - * of the OS. + * Returns: true if @mount_path is considered an implementation detail + * of the OS; false otherwise **/ gboolean g_unix_is_mount_path_system_internal (const char *mount_path) @@ -348,14 +350,17 @@ g_unix_is_mount_path_system_internal (const char *mount_path) * @fs_type: a file system type, e.g. `procfs` or `tmpfs` * * Determines if @fs_type is considered a type of file system which is only - * used in implementation of the OS. This is primarily used for hiding - * mounted volumes that are intended as APIs for programs to read, and system - * administrators at a shell; rather than something that should, for example, - * appear in a GUI. For example, the Linux `/proc` filesystem. + * used in implementation of the OS. + * + * This is primarily used for hiding mounted volumes that are intended as APIs + * for programs to read, and system administrators at a shell; rather than + * something that should, for example, appear in a GUI. For example, the Linux + * `/proc` filesystem. * * The list of file system types considered ‘system’ ones may change over time. * - * Returns: %TRUE if @fs_type is considered an implementation detail of the OS. + * Returns: true if @fs_type is considered an implementation detail of the OS; + * false otherwise * Since: 2.56 */ gboolean @@ -417,15 +422,17 @@ g_unix_is_system_fs_type (const char *fs_type) * @device_path: a device path, e.g. `/dev/loop0` or `nfsd` * * Determines if @device_path is considered a block device path which is only - * used in implementation of the OS. This is primarily used for hiding - * mounted volumes that are intended as APIs for programs to read, and system - * administrators at a shell; rather than something that should, for example, - * appear in a GUI. For example, the Linux `/proc` filesystem. + * used in implementation of the OS. + * + * This is primarily used for hiding mounted volumes that are intended as APIs + * for programs to read, and system administrators at a shell; rather than + * something that should, for example, appear in a GUI. For example, the Linux + * `/proc` filesystem. * * The list of device paths considered ‘system’ ones may change over time. * - * Returns: %TRUE if @device_path is considered an implementation detail of - * the OS. + * Returns: true if @device_path is considered an implementation detail of + * the OS; false otherwise * Since: 2.56 */ gboolean @@ -1806,17 +1813,18 @@ get_mount_points_timestamp (void) /** * g_unix_mounts_get: - * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL + * @time_read: (out) (optional): return location for a timestamp * - * Gets a #GList of #GUnixMountEntry containing the Unix mounts. - * If @time_read is set, it will be filled with the mount - * timestamp, allowing for checking if the mounts have changed - * with g_unix_mount_entries_changed_since(). + * Gets a list of [struct@GioUnix.MountEntry] instances representing the Unix + * mounts. * - * Returns: (element-type GUnixMountEntry) (transfer full): - * a #GList of the Unix mounts. + * If @time_read is set, it will be filled with the mount timestamp, allowing + * for checking if the mounts have changed with + * [func@GioUnix.mount_entries_changed_since]. * - * Deprecated: 2.84: Use g_unix_mount_entries_get() instead. + * Returns: (element-type GUnixMountEntry) (transfer full): a list of the + * Unix mounts + * Deprecated: 2.84: Use [func@GioUnix.mount_entries_get] instead. */ GList * g_unix_mounts_get (guint64 *time_read) @@ -1826,16 +1834,17 @@ g_unix_mounts_get (guint64 *time_read) /** * g_unix_mount_entries_get: - * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL + * @time_read: (out) (optional): return location for a timestamp * - * Gets a #GList of #GUnixMountEntry containing the Unix mounts. - * If @time_read is set, it will be filled with the mount - * timestamp, allowing for checking if the mounts have changed - * with g_unix_mount_entries_changed_since(). + * Gets a list of [struct@GioUnix.MountEntry] instances representing the Unix + * mounts. * - * Returns: (element-type GUnixMountEntry) (transfer full): - * a #GList of the Unix mounts. + * If @time_read is set, it will be filled with the mount timestamp, allowing + * for checking if the mounts have changed with + * [func@GioUnix.mount_entries_changed_since]. * + * Returns: (element-type GUnixMountEntry) (transfer full): a list of the + * Unix mounts * Since: 2.84 */ GList * @@ -1858,19 +1867,18 @@ g_unix_mount_entries_get (guint64 *time_read) * Gets an array of [struct@Gio.UnixMountEntry]s containing the Unix mounts * listed in @table_path. * - * This is a generalized version of g_unix_mount_entries_get(), mainly intended for - * internal testing use. Note that g_unix_mount_entries_get() may parse multiple - * hierarchical table files, so this function is not a direct superset of its - * functionality. + * This is a generalized version of [func@GioUnix.mount_entries_get], mainly + * intended for internal testing use. Note that [func@GioUnix.mount_entries_get] + * may parse multiple hierarchical table files, so this function is not a direct + * superset of its functionality. * * If there is an error reading or parsing the file, `NULL` will be returned * and both out parameters will be set to `0`. * * Returns: (transfer full) (array length=n_entries_out) (nullable): mount * entries, or `NULL` if there was an error loading them - * * Since: 2.82 - * Deprecated: 2.84: Use g_unix_mount_entries_get_from_file() instead. + * Deprecated: 2.84: Use [func@GioUnix.mount_entries_get_from_file] instead. */ GUnixMountEntry ** g_unix_mounts_get_from_file (const char *table_path, @@ -1891,17 +1899,16 @@ g_unix_mounts_get_from_file (const char *table_path, * Gets an array of [struct@Gio.UnixMountEntry]s containing the Unix mounts * listed in @table_path. * - * This is a generalized version of g_unix_mount_entries_get(), mainly intended for - * internal testing use. Note that g_unix_mount_entries_get() may parse multiple - * hierarchical table files, so this function is not a direct superset of its - * functionality. + * This is a generalized version of [func@GioUnix.mount_entries_get], mainly + * intended for internal testing use. Note that [func@GioUnix.mount_entries_get] + * may parse multiple hierarchical table files, so this function is not a direct + * superset of its functionality. * * If there is an error reading or parsing the file, `NULL` will be returned * and both out parameters will be set to `0`. * * Returns: (transfer full) (array length=n_entries_out) (nullable): mount * entries, or `NULL` if there was an error loading them - * * Since: 2.84 */ GUnixMountEntry ** @@ -1914,21 +1921,22 @@ g_unix_mount_entries_get_from_file (const char *table_path, /** * g_unix_mount_at: - * @mount_path: (type filename): path for a possible Unix mount. - * @time_read: (out) (optional): guint64 to contain a timestamp. + * @mount_path: (type filename): path for a possible Unix mount + * @time_read: (out) (optional): return location for a timestamp * - * Gets a #GUnixMountEntry for a given mount path. If @time_read - * is set, it will be filled with a Unix timestamp for checking - * if the mounts have changed since with g_unix_mount_entries_changed_since(). + * Gets a [struct@GioUnix.MountEntry] for a given mount path. + * + * If @time_read is set, it will be filled with a Unix timestamp for checking + * if the mounts have changed since with + * [func@GioUnix.mount_entries_changed_since]. * * If more mounts have the same mount path, the last matching mount * is returned. * - * This will return %NULL if there is no mount point at @mount_path. + * This will return `NULL` if there is no mount point at @mount_path. * - * Returns: (transfer full) (nullable): a #GUnixMountEntry. - * - * Deprecated: 2.84: Use g_unix_mount_entry_at() instead. + * Returns: (transfer full) (nullable): a [struct@GioUnix.MountEntry] + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.at] instead. **/ GUnixMountEntry * g_unix_mount_at (const char *mount_path, @@ -1939,20 +1947,21 @@ g_unix_mount_at (const char *mount_path, /** * g_unix_mount_entry_at: - * @mount_path: (type filename): path for a possible Unix mount. - * @time_read: (out) (optional): guint64 to contain a timestamp. + * @mount_path: (type filename): path for a possible Unix mount + * @time_read: (out) (optional): return location for a timestamp * - * Gets a #GUnixMountEntry for a given mount path. If @time_read - * is set, it will be filled with a Unix timestamp for checking - * if the mounts have changed since with g_unix_mount_entries_changed_since(). + * Gets a [struct@GioUnix.MountEntry] for a given mount path. + * + * If @time_read is set, it will be filled with a Unix timestamp for checking + * if the mounts have changed since with + * [func@GioUnix.mount_entries_changed_since]. * * If more mounts have the same mount path, the last matching mount * is returned. * - * This will return %NULL if there is no mount point at @mount_path. - * - * Returns: (transfer full) (nullable): a #GUnixMountEntry. + * This will return `NULL` if there is no mount point at @mount_path. * + * Returns: (transfer full) (nullable): a [struct@GioUnix.MountEntry] * Since: 2.84 **/ GUnixMountEntry * @@ -1986,23 +1995,24 @@ g_unix_mount_entry_at (const char *mount_path, /** * g_unix_mount_for: - * @file_path: (type filename): file path on some Unix mount. - * @time_read: (out) (optional): guint64 to contain a timestamp. + * @file_path: (type filename): file path on some Unix mount + * @time_read: (out) (optional): return location for a timestamp * - * Gets a #GUnixMountEntry for a given file path. If @time_read - * is set, it will be filled with a Unix timestamp for checking - * if the mounts have changed since with g_unix_mount_entries_changed_since(). + * Gets a [struct@GioUnix.MountEntry] for a given file path. + * + * If @time_read is set, it will be filled with a Unix timestamp for checking + * if the mounts have changed since with + * [func@GioUnix.mount_entries_changed_since]. * * If more mounts have the same mount path, the last matching mount * is returned. * - * This will return %NULL if looking up the mount entry fails, if + * This will return `NULL` if looking up the mount entry fails, if * @file_path doesn’t exist or there is an I/O error. * - * Returns: (transfer full) (nullable): a #GUnixMountEntry. - * + * Returns: (transfer full) (nullable): a [struct@GioUnix.MountEntry] * Since: 2.52 - * Deprecated: 2.84: Use g_unix_mount_entry_for() instead. + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.for] instead. **/ GUnixMountEntry * g_unix_mount_for (const char *file_path, @@ -2013,21 +2023,22 @@ g_unix_mount_for (const char *file_path, /** * g_unix_mount_entry_for: - * @file_path: (type filename): file path on some Unix mount. - * @time_read: (out) (optional): guint64 to contain a timestamp. + * @file_path: (type filename): file path on some Unix mount + * @time_read: (out) (optional): return location for a timestamp * - * Gets a #GUnixMountEntry for a given file path. If @time_read - * is set, it will be filled with a Unix timestamp for checking - * if the mounts have changed since with g_unix_mount_entries_changed_since(). + * Gets a [struct@GioUnix.MountEntry] for a given file path. + * + * If @time_read is set, it will be filled with a Unix timestamp for checking + * if the mounts have changed since with + * [func@GioUnix.mount_entries_changed_since]. * * If more mounts have the same mount path, the last matching mount * is returned. * - * This will return %NULL if looking up the mount entry fails, if + * This will return `NULL` if looking up the mount entry fails, if * @file_path doesn’t exist or there is an I/O error. * - * Returns: (transfer full) (nullable): a #GUnixMountEntry. - * + * Returns: (transfer full) (nullable): a [struct@GioUnix.MountEntry] * Since: 2.84 **/ GUnixMountEntry * @@ -2064,15 +2075,17 @@ copy_mount_point_cb (gconstpointer src, /** * g_unix_mount_points_get: - * @time_read: (out) (optional): guint64 to contain a timestamp. + * @time_read: (out) (optional): return location for a timestamp * - * Gets a #GList of #GUnixMountPoint containing the Unix mount points. - * If @time_read is set, it will be filled with the mount timestamp, - * allowing for checking if the mounts have changed with - * g_unix_mount_points_changed_since(). + * Gets a list of [struct@GioUnix.MountPoint] instances representing the Unix + * mount points. * - * Returns: (element-type GUnixMountPoint) (transfer full): - * a #GList of the Unix mountpoints. + * If @time_read is set, it will be filled with the mount timestamp, allowing + * for checking if the mounts have changed with + * [func@GioUnix.mount_points_changed_since]. + * + * Returns: (element-type GUnixMountPoint) (transfer full): a list of the Unix + * mount points **/ GList * g_unix_mount_points_get (guint64 *time_read) @@ -2113,10 +2126,10 @@ g_unix_mount_points_get (guint64 *time_read) * Gets an array of [struct@Gio.UnixMountPoint]s containing the Unix mount * points listed in @table_path. * - * This is a generalized version of g_unix_mount_points_get(), mainly intended - * for internal testing use. Note that g_unix_mount_points_get() may parse - * multiple hierarchical table files, so this function is not a direct superset - * of its functionality. + * This is a generalized version of [func@GioUnix.mount_points_get], mainly + * intended for internal testing use. Note that [func@GioUnix.mount_points_get] + * may parse multiple hierarchical table files, so this function is not a direct + * superset of its functionality. * * If there is an error reading or parsing the file, `NULL` will be returned * and both out parameters will be set to `0`. @@ -2135,19 +2148,20 @@ g_unix_mount_points_get_from_file (const char *table_path, /** * g_unix_mount_point_at: - * @mount_path: (type filename): path for a possible Unix mount point. - * @time_read: (out) (optional): guint64 to contain a timestamp. + * @mount_path: (type filename): path for a possible Unix mount point + * @time_read: (out) (optional): return location for a timestamp * - * Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it - * will be filled with a Unix timestamp for checking if the mount points have - * changed since with g_unix_mount_points_changed_since(). + * Gets a [struct@GioUnix.MountPoint] for a given mount path. + * + * If @time_read is set, it will be filled with a Unix timestamp for checking if + * the mount points have changed since with + * [func@GioUnix.mount_points_changed_since]. * * If more mount points have the same mount path, the last matching mount point * is returned. * - * Returns: (transfer full) (nullable): a #GUnixMountPoint, or %NULL if no match - * is found. - * + * Returns: (transfer full) (nullable): a [struct@GioUnix.MountPoint], or `NULL` + * if no match is found * Since: 2.66 **/ GUnixMountPoint * @@ -2181,13 +2195,12 @@ g_unix_mount_point_at (const char *mount_path, /** * g_unix_mounts_changed_since: - * @time: guint64 to contain a timestamp. + * @time: a timestamp * * Checks if the Unix mounts have changed since a given Unix time. * - * Returns: %TRUE if the mounts have changed since @time. - * - * Deprecated: 2.84: Use g_unix_mount_entries_changed_since() instead. + * Returns: true if the mounts have changed since @time; false otherwise + * Deprecated: 2.84: Use [func@GioUnix.mount_entries_changed_since] instead. **/ gboolean g_unix_mounts_changed_since (guint64 time) @@ -2197,7 +2210,7 @@ g_unix_mounts_changed_since (guint64 time) /** * g_unix_mount_entries_changed_since: - * @time: guint64 to contain a timestamp. + * @time: a timestamp * * Checks if the Unix mounts have changed since a given Unix time. * @@ -2211,7 +2224,7 @@ g_unix_mounts_changed_since (guint64 time) * function. This function is more appropriate for infrequently determining * cache validity. * - * Returns: %TRUE if the mounts have changed since @time. + * Returns: true if the mounts have changed since @time; false otherwise * Since 2.84 **/ gboolean @@ -2222,7 +2235,7 @@ g_unix_mount_entries_changed_since (guint64 time) /** * g_unix_mount_points_changed_since: - * @time: guint64 to contain a timestamp. + * @time: a timestamp * * Checks if the Unix mount points have changed since a given Unix time. * @@ -2236,7 +2249,7 @@ g_unix_mount_entries_changed_since (guint64 time) * this function. This function is more appropriate for infrequently determining * cache validity. * - * Returns: %TRUE if the mount points have changed since @time. + * Returns: true if the mount points have changed since @time; false otherwise **/ gboolean g_unix_mount_points_changed_since (guint64 time) @@ -2603,7 +2616,7 @@ g_unix_mount_monitor_class_init (GUnixMountMonitorClass *klass) * GUnixMountMonitor::mounts-changed: * @monitor: the object on which the signal is emitted * - * Emitted when the Unix mounts have changed. + * Emitted when the Unix mount entries have changed. */ signals[MOUNTS_CHANGED] = g_signal_new (I_("mounts-changed"), @@ -2637,9 +2650,8 @@ g_unix_mount_monitor_init (GUnixMountMonitor *monitor) /** * g_unix_mount_monitor_set_rate_limit: - * @mount_monitor: a #GUnixMountMonitor - * @limit_msec: a integer with the limit in milliseconds to - * poll for changes. + * @mount_monitor: a [class@GioUnix.MountMonitor] + * @limit_msec: a integer with the limit (in milliseconds) to poll for changes * * This function does nothing. * @@ -2650,8 +2662,7 @@ g_unix_mount_monitor_init (GUnixMountMonitor *monitor) * the monitor. * * Since: 2.18 - * - * Deprecated:2.44:This function does nothing. Don't call it. + * Deprecated: 2.44: This function does nothing. Don’t call it. */ void g_unix_mount_monitor_set_rate_limit (GUnixMountMonitor *mount_monitor, @@ -2662,18 +2673,17 @@ g_unix_mount_monitor_set_rate_limit (GUnixMountMonitor *mount_monitor, /** * g_unix_mount_monitor_get: * - * Gets the #GUnixMountMonitor for the current thread-default main + * Gets the [class@GioUnix.MountMonitor] for the current thread-default main * context. * * The mount monitor can be used to monitor for changes to the list of * mounted filesystems as well as the list of mount points (ie: fstab * entries). * - * You must only call g_object_unref() on the return value from under - * the same main context as you called this function. - * - * Returns: (transfer full): the #GUnixMountMonitor. + * You must only call [method@GObject.Object.unref] on the return value from + * under the same main context as you called this function. * + * Returns: (transfer full): the [class@GioUnix.MountMonitor] * Since: 2.44 **/ GUnixMountMonitor * @@ -2688,14 +2698,13 @@ g_unix_mount_monitor_get (void) /** * g_unix_mount_monitor_new: * - * Deprecated alias for g_unix_mount_monitor_get(). + * Deprecated alias for [func@GioUnix.MountMonitor.get]. * * This function was never a true constructor, which is why it was * renamed. * - * Returns: a #GUnixMountMonitor. - * - * Deprecated:2.44:Use g_unix_mount_monitor_get() instead. + * Returns: a [class@GioUnix.MountMonitor] + * Deprecated: 2.44: Use [func@GioUnix.MountMonitor.get] instead. */ GUnixMountMonitor * g_unix_mount_monitor_new (void) @@ -2706,11 +2715,11 @@ g_unix_mount_monitor_new (void) /* GUnixMount {{{1 */ /** * g_unix_mount_free: - * @mount_entry: a #GUnixMountEntry. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Frees a Unix mount. * - * Deprecated: 2.84: Use g_unix_mount_entry_free() instead. + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.free] instead. */ void g_unix_mount_free (GUnixMountEntry *mount_entry) @@ -2720,7 +2729,7 @@ g_unix_mount_free (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_free: - * @mount_entry: a #GUnixMountEntry. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Frees a Unix mount. * @@ -2741,14 +2750,13 @@ g_unix_mount_entry_free (GUnixMountEntry *mount_entry) /** * g_unix_mount_copy: - * @mount_entry: a #GUnixMountEntry. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Makes a copy of @mount_entry. * - * Returns: (transfer full): a new #GUnixMountEntry - * + * Returns: (transfer full): a new [struct@GioUnix.MountEntry] * Since: 2.54 - * Deprecated: 2.84: Use g_unix_mount_entry_copy() instead. + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.copy] instead. */ GUnixMountEntry * g_unix_mount_copy (GUnixMountEntry *mount_entry) @@ -2758,12 +2766,11 @@ g_unix_mount_copy (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_copy: - * @mount_entry: a #GUnixMountEntry. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Makes a copy of @mount_entry. * - * Returns: (transfer full): a new #GUnixMountEntry - * + * Returns: (transfer full): a new [struct@GioUnix.MountEntry] * Since: 2.84 */ GUnixMountEntry * @@ -2805,12 +2812,11 @@ g_unix_mount_point_free (GUnixMountPoint *mount_point) /** * g_unix_mount_point_copy: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Makes a copy of @mount_point. * - * Returns: (transfer full): a new #GUnixMountPoint - * + * Returns: (transfer full): a new [struct@GioUnix.MountPoint] * Since: 2.54 */ GUnixMountPoint* @@ -2834,15 +2840,14 @@ g_unix_mount_point_copy (GUnixMountPoint *mount_point) /** * g_unix_mount_compare: - * @mount1: first #GUnixMountEntry to compare. - * @mount2: second #GUnixMountEntry to compare. + * @mount1: first [struct@GioUnix.MountEntry] to compare + * @mount2: second [struct@GioUnix.MountEntry] to compare * * Compares two Unix mounts. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, - * or less than @mount2, respectively. - * - * Deprecated: 2.84: Use g_unix_mount_entry_compare() instead. + * Returns: `1`, `0` or `-1` if @mount1 is greater than, equal to, + * or less than @mount2, respectively + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.compare] instead. */ gint g_unix_mount_compare (GUnixMountEntry *mount1, @@ -2853,14 +2858,13 @@ g_unix_mount_compare (GUnixMountEntry *mount1, /** * g_unix_mount_entry_compare: - * @mount1: first #GUnixMountEntry to compare. - * @mount2: second #GUnixMountEntry to compare. + * @mount1: first [struct@GioUnix.MountEntry] to compare + * @mount2: second [struct@GioUnix.MountEntry] to compare * * Compares two Unix mounts. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, - * or less than @mount2, respectively. - * + * Returns: `1`, `0` or `-1` if @mount1 is greater than, equal to, + * or less than @mount2, respectively * Since: 2.84 */ gint @@ -2900,13 +2904,12 @@ g_unix_mount_entry_compare (GUnixMountEntry *mount1, /** * g_unix_mount_get_mount_path: - * @mount_entry: input #GUnixMountEntry to get the mount path for. + * @mount_entry: a [struct@GioUnix.MountEntry] to get the mount path for * * Gets the mount path for a Unix mount. * - * Returns: (type filename): the mount path for @mount_entry. - * - * Deprecated: 2.84: Use g_unix_mount_entry_get_mount_path() instead. + * Returns: (type filename): the mount path for @mount_entry + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.get_mount_path] instead. */ const gchar * g_unix_mount_get_mount_path (GUnixMountEntry *mount_entry) @@ -2916,12 +2919,11 @@ g_unix_mount_get_mount_path (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_get_mount_path: - * @mount_entry: input #GUnixMountEntry to get the mount path for. + * @mount_entry: a [struct@GioUnix.MountEntry] to get the mount path for * * Gets the mount path for a Unix mount. * - * Returns: (type filename): the mount path for @mount_entry. - * + * Returns: (type filename): the mount path for @mount_entry * Since: 2.84 */ const gchar * @@ -2934,13 +2936,12 @@ g_unix_mount_entry_get_mount_path (GUnixMountEntry *mount_entry) /** * g_unix_mount_get_device_path: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Gets the device path for a Unix mount. * - * Returns: (type filename): a string containing the device path. - * - * Deprecated: 2.84: Use g_unix_mount_entry_get_device_path() instead. + * Returns: (type filename): a string containing the device path + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.get_device_path] instead. */ const gchar * g_unix_mount_get_device_path (GUnixMountEntry *mount_entry) @@ -2950,12 +2951,11 @@ g_unix_mount_get_device_path (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_get_device_path: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Gets the device path for a Unix mount. * - * Returns: (type filename): a string containing the device path. - * + * Returns: (type filename): a string containing the device path * Since: 2.84 */ const gchar * @@ -2968,19 +2968,18 @@ g_unix_mount_entry_get_device_path (GUnixMountEntry *mount_entry) /** * g_unix_mount_get_root_path: - * @mount_entry: a #GUnixMountEntry. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Gets the root of the mount within the filesystem. This is useful e.g. for * mounts created by bind operation, or btrfs subvolumes. * - * For example, the root path is equal to "/" for mount created by - * "mount /dev/sda1 /mnt/foo" and "/bar" for - * "mount --bind /mnt/foo/bar /mnt/bar". - * - * Returns: (nullable): a string containing the root, or %NULL if not supported. + * For example, the root path is equal to `/` for a mount created by + * `mount /dev/sda1 /mnt/foo` and `/bar` for + * `mount --bind /mnt/foo/bar /mnt/bar`. * + * Returns: (nullable): a string containing the root, or `NULL` if not supported * Since: 2.60 - * Deprecated: 2.84: Use g_unix_mount_entry_get_root_path() instead. + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.get_root_path] instead. */ const gchar * g_unix_mount_get_root_path (GUnixMountEntry *mount_entry) @@ -2990,17 +2989,16 @@ g_unix_mount_get_root_path (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_get_root_path: - * @mount_entry: a #GUnixMountEntry. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Gets the root of the mount within the filesystem. This is useful e.g. for * mounts created by bind operation, or btrfs subvolumes. * - * For example, the root path is equal to "/" for mount created by - * "mount /dev/sda1 /mnt/foo" and "/bar" for - * "mount --bind /mnt/foo/bar /mnt/bar". - * - * Returns: (nullable): a string containing the root, or %NULL if not supported. + * For example, the root path is equal to `/` for a mount created by + * `mount /dev/sda1 /mnt/foo` and `/bar` for + * `mount --bind /mnt/foo/bar /mnt/bar`. * + * Returns: (nullable): a string containing the root, or `NULL` if not supported * Since: 2.84 */ const gchar * @@ -3013,13 +3011,12 @@ g_unix_mount_entry_get_root_path (GUnixMountEntry *mount_entry) /** * g_unix_mount_get_fs_type: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Gets the filesystem type for the Unix mount. * - * Returns: a string containing the file system type. - * - * Deprecated: 2.84: Use g_unix_mount_entry_get_fs_type() instead. + * Returns: a string containing the file system type + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.get_fs_type] instead. */ const gchar * g_unix_mount_get_fs_type (GUnixMountEntry *mount_entry) @@ -3029,12 +3026,11 @@ g_unix_mount_get_fs_type (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_get_fs_type: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Gets the filesystem type for the Unix mount. * - * Returns: a string containing the file system type. - * + * Returns: a string containing the file system type * Since: 2.84 */ const gchar * @@ -3047,19 +3043,19 @@ g_unix_mount_entry_get_fs_type (GUnixMountEntry *mount_entry) /** * g_unix_mount_get_options: - * @mount_entry: a #GUnixMountEntry. + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Gets a comma-separated list of mount options for the Unix mount. For example, - * `rw,relatime,seclabel,data=ordered`. + * Gets a comma separated list of mount options for the Unix mount. * - * This is similar to g_unix_mount_point_get_options(), but it takes - * a #GUnixMountEntry as an argument. + * For example: `rw,relatime,seclabel,data=ordered`. * - * Returns: (nullable): a string containing the options, or %NULL if not - * available. + * This is similar to [func@GioUnix.MountPoint.get_options], but it takes + * a [struct@GioUnix.MountEntry] as an argument. * + * Returns: (nullable): a string containing the options, or `NULL` if not + * available. * Since: 2.58 - * Deprecated: 2.84: Use g_unix_mount_entry_get_options() instead. + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.get_options] instead. */ const gchar * g_unix_mount_get_options (GUnixMountEntry *mount_entry) @@ -3069,17 +3065,17 @@ g_unix_mount_get_options (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_get_options: - * @mount_entry: a #GUnixMountEntry. + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Gets a comma-separated list of mount options for the Unix mount. For example, - * `rw,relatime,seclabel,data=ordered`. + * Gets a comma separated list of mount options for the Unix mount. * - * This is similar to g_unix_mount_point_get_options(), but it takes - * a #GUnixMountEntry as an argument. + * For example: `rw,relatime,seclabel,data=ordered`. * - * Returns: (nullable): a string containing the options, or %NULL if not - * available. + * This is similar to [func@GioUnix.MountPoint.get_options], but it takes + * a [struct@GioUnix.MountEntry] as an argument. * + * Returns: (nullable): a string containing the options, or `NULL` if not + * available. * Since: 2.84 */ const gchar * @@ -3092,13 +3088,12 @@ g_unix_mount_entry_get_options (GUnixMountEntry *mount_entry) /** * g_unix_mount_is_readonly: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Checks if a Unix mount is mounted read only. * - * Returns: %TRUE if @mount_entry is read only. - * - * Deprecated: 2.84: Use g_unix_mount_entry_is_readonly() instead. + * Returns: true if @mount_entry is read only; false otherwise + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.is_readonly] instead. */ gboolean g_unix_mount_is_readonly (GUnixMountEntry *mount_entry) @@ -3108,12 +3103,11 @@ g_unix_mount_is_readonly (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_is_readonly: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] * * Checks if a Unix mount is mounted read only. * - * Returns: %TRUE if @mount_entry is read only. - * + * Returns: true if @mount_entry is read only; false otherwise * Since: 2.84 */ gboolean @@ -3126,18 +3120,19 @@ g_unix_mount_entry_is_readonly (GUnixMountEntry *mount_entry) /** * g_unix_mount_is_system_internal: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Checks if a Unix mount is a system mount. This is the Boolean OR of - * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and - * g_unix_is_mount_path_system_internal() on @mount_entry’s properties. + * Checks if a Unix mount is a system mount. + * + * This is the Boolean OR of + * [func@GioUnix.is_system_fs_type], [func@GioUnix.is_system_device_path] and + * [func@GioUnix.is_mount_path_system_internal] on @mount_entry’s properties. * * The definition of what a ‘system’ mount entry is may change over time as new * file system types and device paths are ignored. * - * Returns: %TRUE if the Unix mount is for a system path. - * - * Deprecated: 2.84: Use g_unix_mount_entry_is_system_internal() instead. + * Returns: true if the Unix mount is for a system path; false otherwise + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.is_system_internal] instead. */ gboolean g_unix_mount_is_system_internal (GUnixMountEntry *mount_entry) @@ -3147,17 +3142,18 @@ g_unix_mount_is_system_internal (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_is_system_internal: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Checks if a Unix mount is a system mount. This is the Boolean OR of - * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and - * g_unix_is_mount_path_system_internal() on @mount_entry’s properties. + * Checks if a Unix mount is a system mount. + * + * This is the Boolean OR of + * [func@GioUnix.is_system_fs_type], [func@GioUnix.is_system_device_path] and + * [func@GioUnix.is_mount_path_system_internal] on @mount_entry’s properties. * * The definition of what a ‘system’ mount entry is may change over time as new * file system types and device paths are ignored. * - * Returns: %TRUE if the Unix mount is for a system path. - * + * Returns: true if the Unix mount is for a system path; false otherwise * Since: 2.84 */ gboolean @@ -3171,13 +3167,13 @@ g_unix_mount_entry_is_system_internal (GUnixMountEntry *mount_entry) /* GUnixMountPoint {{{1 */ /** * g_unix_mount_point_compare: - * @mount1: a #GUnixMount. - * @mount2: a #GUnixMount. + * @mount1: a [struct@GioUnix.MountPoint] + * @mount2: a [struct@GioUnix.MountPoint] * * Compares two Unix mount points. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, - * or less than @mount2, respectively. + * Returns: `1`, `0` or `-1` if @mount1 is greater than, equal to, + * or less than @mount2, respectively */ gint g_unix_mount_point_compare (GUnixMountPoint *mount1, @@ -3220,11 +3216,11 @@ g_unix_mount_point_compare (GUnixMountPoint *mount1, /** * g_unix_mount_point_get_mount_path: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Gets the mount path for a Unix mount point. * - * Returns: (type filename): a string containing the mount path. + * Returns: (type filename): a string containing the mount path */ const gchar * g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point) @@ -3236,11 +3232,11 @@ g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point) /** * g_unix_mount_point_get_device_path: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Gets the device path for a Unix mount point. * - * Returns: (type filename): a string containing the device path. + * Returns: (type filename): a string containing the device path */ const gchar * g_unix_mount_point_get_device_path (GUnixMountPoint *mount_point) @@ -3252,11 +3248,11 @@ g_unix_mount_point_get_device_path (GUnixMountPoint *mount_point) /** * g_unix_mount_point_get_fs_type: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Gets the file system type for the mount point. * - * Returns: a string containing the file system type. + * Returns: a string containing the file system type */ const gchar * g_unix_mount_point_get_fs_type (GUnixMountPoint *mount_point) @@ -3268,12 +3264,11 @@ g_unix_mount_point_get_fs_type (GUnixMountPoint *mount_point) /** * g_unix_mount_point_get_options: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Gets the options for the mount point. * - * Returns: (nullable): a string containing the options. - * + * Returns: (nullable): a string containing the options * Since: 2.32 */ const gchar * @@ -3286,11 +3281,11 @@ g_unix_mount_point_get_options (GUnixMountPoint *mount_point) /** * g_unix_mount_point_is_readonly: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Checks if a Unix mount point is read only. * - * Returns: %TRUE if a mount point is read only. + * Returns: true if a mount point is read only; false otherwise */ gboolean g_unix_mount_point_is_readonly (GUnixMountPoint *mount_point) @@ -3302,11 +3297,11 @@ g_unix_mount_point_is_readonly (GUnixMountPoint *mount_point) /** * g_unix_mount_point_is_user_mountable: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Checks if a Unix mount point is mountable by the user. * - * Returns: %TRUE if the mount point is user mountable. + * Returns: true if the mount point is user mountable; false otherwise */ gboolean g_unix_mount_point_is_user_mountable (GUnixMountPoint *mount_point) @@ -3318,11 +3313,11 @@ g_unix_mount_point_is_user_mountable (GUnixMountPoint *mount_point) /** * g_unix_mount_point_is_loopback: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Checks if a Unix mount point is a loopback device. * - * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. + * Returns: true if the mount point is a loopback device; false otherwise */ gboolean g_unix_mount_point_is_loopback (GUnixMountPoint *mount_point) @@ -3414,12 +3409,14 @@ guess_mount_type (const char *mount_path, /** * g_unix_mount_entry_guess_type: - * @mount_entry: a #GUnixMount. + * @mount_entry: a [struct@GioUnix.MountEntry] + * + * Guesses the type of a Unix mount entry. * - * Guesses the type of a Unix mount. If the mount type cannot be - * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. + * If the mount type cannot be determined, returns + * [enum@GioUnix.MountType.UNKNOWN]. * - * Returns: a #GUnixMountType. + * Returns: a [enum@GioUnix.MountType] */ static GUnixMountType g_unix_mount_entry_guess_type (GUnixMountEntry *mount_entry) @@ -3436,13 +3433,14 @@ g_unix_mount_entry_guess_type (GUnixMountEntry *mount_entry) /** * g_unix_mount_point_guess_type: - * @mount_point: a #GUnixMountPoint. + * @mount_point: a [struct@GioUnix.MountPoint] * * Guesses the type of a Unix mount point. - * If the mount type cannot be determined, - * returns %G_UNIX_MOUNT_TYPE_UNKNOWN. + * + * If the mount type cannot be determined, returns + * [enum@GioUnix.MountType.UNKNOWN]. * - * Returns: a #GUnixMountType. + * Returns: a [enum@GioUnix.MountType] */ static GUnixMountType g_unix_mount_point_guess_type (GUnixMountPoint *mount_point) @@ -3519,15 +3517,14 @@ type_to_icon (GUnixMountType type, gboolean is_mount_point, gboolean use_symboli /** * g_unix_mount_guess_name: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] + * + * Guesses the name of a Unix mount entry. * - * Guesses the name of a Unix mount. * The result is a translated string. * - * Returns: A newly allocated string that must - * be freed with g_free() - * - * Deprecated: 2.84: Use g_unix_mount_entry_guess_name() instead. + * Returns: (transfer full): a newly allocated translated string + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.guess_name] instead. */ gchar * g_unix_mount_guess_name (GUnixMountEntry *mount_entry) @@ -3537,14 +3534,13 @@ g_unix_mount_guess_name (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_guess_name: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] + * + * Guesses the name of a Unix mount entry. * - * Guesses the name of a Unix mount. * The result is a translated string. * - * Returns: A newly allocated string that must - * be freed with g_free() - * + * Returns: (transfer full): a newly allocated translated string * Since: 2.84 */ gchar * @@ -3562,13 +3558,12 @@ g_unix_mount_entry_guess_name (GUnixMountEntry *mount_entry) /** * g_unix_mount_guess_icon: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Guesses the icon of a Unix mount. + * Guesses the icon of a Unix mount entry. * - * Returns: (transfer full): a #GIcon - * - * Deprecated: 2.84: Use g_unix_mount_entry_guess_icon() instead. + * Returns: (transfer full): a [iface@Gio.Icon] + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.guess_icon] instead. */ GIcon * g_unix_mount_guess_icon (GUnixMountEntry *mount_entry) @@ -3578,12 +3573,11 @@ g_unix_mount_guess_icon (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_guess_icon: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Guesses the icon of a Unix mount. - * - * Returns: (transfer full): a #GIcon + * Guesses the icon of a Unix mount entry. * + * Returns: (transfer full): a [iface@Gio.Icon] * Since: 2.84 */ GIcon * @@ -3594,14 +3588,13 @@ g_unix_mount_entry_guess_icon (GUnixMountEntry *mount_entry) /** * g_unix_mount_guess_symbolic_icon: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Guesses the symbolic icon of a Unix mount. - * - * Returns: (transfer full): a #GIcon + * Guesses the symbolic icon of a Unix mount entry. * + * Returns: (transfer full): a [iface@Gio.Icon] * Since: 2.34 - * Deprecated: 2.84: Use g_unix_mount_entry_guess_symbolic_icon() instead. + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.guess_symbolic_icon] instead. */ GIcon * g_unix_mount_guess_symbolic_icon (GUnixMountEntry *mount_entry) @@ -3611,12 +3604,11 @@ g_unix_mount_guess_symbolic_icon (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_guess_symbolic_icon: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Guesses the symbolic icon of a Unix mount. - * - * Returns: (transfer full): a #GIcon + * Guesses the symbolic icon of a Unix mount entry. * + * Returns: (transfer full): a [iface@Gio.Icon] * Since: 2.84 */ GIcon * @@ -3627,13 +3619,13 @@ g_unix_mount_entry_guess_symbolic_icon (GUnixMountEntry *mount_entry) /** * g_unix_mount_point_guess_name: - * @mount_point: a #GUnixMountPoint + * @mount_point: a [struct@GioUnix.MountPoint] + * + * Guesses the name of a Unix mount point. * - * Guesses the name of a Unix mount point. * The result is a translated string. * - * Returns: A newly allocated string that must - * be freed with g_free() + * Returns: (transfer full): a newly allocated translated string */ gchar * g_unix_mount_point_guess_name (GUnixMountPoint *mount_point) @@ -3650,11 +3642,11 @@ g_unix_mount_point_guess_name (GUnixMountPoint *mount_point) /** * g_unix_mount_point_guess_icon: - * @mount_point: a #GUnixMountPoint + * @mount_point: a [struct@GioUnix.MountPoint] * - * Guesses the icon of a Unix mount point. + * Guesses the icon of a Unix mount point. * - * Returns: (transfer full): a #GIcon + * Returns: (transfer full): a [iface@Gio.Icon] */ GIcon * g_unix_mount_point_guess_icon (GUnixMountPoint *mount_point) @@ -3664,12 +3656,11 @@ g_unix_mount_point_guess_icon (GUnixMountPoint *mount_point) /** * g_unix_mount_point_guess_symbolic_icon: - * @mount_point: a #GUnixMountPoint + * @mount_point: a [struct@GioUnix.MountPoint] * * Guesses the symbolic icon of a Unix mount point. * - * Returns: (transfer full): a #GIcon - * + * Returns: (transfer full): a [iface@Gio.Icon] * Since: 2.34 */ GIcon * @@ -3680,13 +3671,12 @@ g_unix_mount_point_guess_symbolic_icon (GUnixMountPoint *mount_point) /** * g_unix_mount_guess_can_eject: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Guesses whether a Unix mount can be ejected. + * Guesses whether a Unix mount entry can be ejected. * - * Returns: %TRUE if @mount_entry is deemed to be ejectable. - * - * Deprecated: 2.84: Use g_unix_mount_entry_guess_can_eject() instead. + * Returns: true if @mount_entry is deemed to be ejectable; false otherwise + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.guess_can_eject] instead. */ gboolean g_unix_mount_guess_can_eject (GUnixMountEntry *mount_entry) @@ -3696,12 +3686,11 @@ g_unix_mount_guess_can_eject (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_guess_can_eject: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Guesses whether a Unix mount can be ejected. - * - * Returns: %TRUE if @mount_entry is deemed to be ejectable. + * Guesses whether a Unix mount entry can be ejected. * + * Returns: true if @mount_entry is deemed to be ejectable; false otherwise * Since: 2.84 */ gboolean @@ -3719,13 +3708,12 @@ g_unix_mount_entry_guess_can_eject (GUnixMountEntry *mount_entry) /** * g_unix_mount_guess_should_display: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Guesses whether a Unix mount should be displayed in the UI. + * Guesses whether a Unix mount entry should be displayed in the UI. * - * Returns: %TRUE if @mount_entry is deemed to be displayable. - * - * Deprecated: 2.84: Use g_unix_mount_entry_guess_should_display() instead. + * Returns: true if @mount_entry is deemed to be displayable; false otherwise + * Deprecated: 2.84: Use [func@GioUnix.MountEntry.guess_should_display] instead. */ gboolean g_unix_mount_guess_should_display (GUnixMountEntry *mount_entry) @@ -3735,11 +3723,11 @@ g_unix_mount_guess_should_display (GUnixMountEntry *mount_entry) /** * g_unix_mount_entry_guess_should_display: - * @mount_entry: a #GUnixMountEntry + * @mount_entry: a [struct@GioUnix.MountEntry] * - * Guesses whether a Unix mount should be displayed in the UI. + * Guesses whether a Unix mount entry should be displayed in the UI. * - * Returns: %TRUE if @mount_entry is deemed to be displayable. + * Returns: true if @mount_entry is deemed to be displayable; false otherwise * Since: 2.84 */ gboolean @@ -3823,11 +3811,11 @@ g_unix_mount_entry_guess_should_display (GUnixMountEntry *mount_entry) /** * g_unix_mount_point_guess_can_eject: - * @mount_point: a #GUnixMountPoint + * @mount_point: a [struct@GioUnix.MountPoint] * * Guesses whether a Unix mount point can be ejected. * - * Returns: %TRUE if @mount_point is deemed to be ejectable. + * Returns: true if @mount_point is deemed to be ejectable; false otherwise */ gboolean g_unix_mount_point_guess_can_eject (GUnixMountPoint *mount_point) diff --git a/gio/gunixmounts.h b/gio/gunixmounts.h index 0e3a0f163..3c35fd349 100644 --- a/gio/gunixmounts.h +++ b/gio/gunixmounts.h @@ -55,7 +55,14 @@ GType g_unix_mount_point_get_type (void) G_GNUC_CONST; /** * GUnixMountMonitor: * - * Watches #GUnixMounts for changes. + * Watches for changes to the set of mount entries and mount points in the + * system. + * + * Connect to the [signal@GioUnix.MountMonitor::mounts-changed] signal to be + * notified of changes to the [struct@GioUnix.MountEntry] list. + * + * Connect to the [signal@GioUnix.MountMonitor::mountpoints-changed] signal to + * be notified of changes to the [struct@GioUnix.MountPoint] list. **/ typedef struct _GUnixMountMonitor GUnixMountMonitor; typedef struct _GUnixMountMonitorClass GUnixMountMonitorClass; From 2ebd1c8f158ea975f2e7757786ebb6009a3f3d92 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 20 Dec 2024 15:13:16 +0000 Subject: [PATCH 5/5] docs: Hide Unix and Win32 symbols from main GLib and GIO docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These symbols are documented in the {glib,gio}-{unix,win32} documentation builds, and shouldn’t be duplicated in the main documentation. It’s a historical (and unavoidable) accident that those symbols are in the main GIR files. If we don’t hide the symbols from the main docs build, we now run into the problem of the `GioUnix` namespace not being known to gi-docgen while building the `Gio` docs. This is because of the previous two commits, which ported more of the `gunixmounts` documentation to gi-docgen syntax. I don’t know of another way to fix this, other than to hide the `GioUnix` symbols from the `Gio` docs build. Signed-off-by: Philip Withnall Helps: #3250 --- docs/reference/gio/gio.toml.in | 35 ++++++++++++++++++++++++++++++++ docs/reference/glib/glib.toml.in | 35 ++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/docs/reference/gio/gio.toml.in b/docs/reference/gio/gio.toml.in index f81439671..7010ecc22 100644 --- a/docs/reference/gio/gio.toml.in +++ b/docs/reference/gio/gio.toml.in @@ -73,3 +73,38 @@ content_images = [ "menu-model-dark.svg", "menu-model-light.svg", ] + +# We have to hide the GioUnix and GioWin32 symbols from the documentation — they +# have to be present in the GIR files (until we next break API), but their +# documentation is split out to gio-{unix,win32}.toml. +[[object]] +pattern = "Unix[A-Z].+" +hidden = true + +[[object]] +pattern = "unix_.+" +hidden = true + +[[struct]] +pattern = "Unix[A-Z].+" +hidden = true + +[[function]] +pattern = "unix_.+" +hidden = true + +[[object]] +pattern = "Win32[A-Z].+" +hidden = true + +[[object]] +pattern = "win32_.+" +hidden = true + +[[struct]] +pattern = "Win32[A-Z].+" +hidden = true + +[[function]] +pattern = "win32_.+" +hidden = true \ No newline at end of file diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 478f47b9c..ecdf2e1ff 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -128,3 +128,38 @@ hidden = true [[object]] pattern = "macro__has_*" hidden = true + +# We have to hide the GioUnix and GioWin32 symbols from the documentation — they +# have to be present in the GIR files (until we next break API), but their +# documentation is split out to glib-{unix,win32}.toml. +[[object]] +pattern = "Unix[A-Z].+" +hidden = true + +[[object]] +pattern = "unix_.+" +hidden = true + +[[struct]] +pattern = "Unix[A-Z].+" +hidden = true + +[[function]] +pattern = "unix_.+" +hidden = true + +[[object]] +pattern = "Win32[A-Z].+" +hidden = true + +[[object]] +pattern = "win32_.+" +hidden = true + +[[struct]] +pattern = "Win32[A-Z].+" +hidden = true + +[[function]] +pattern = "win32_.+" +hidden = true \ No newline at end of file