From e8edaeeb8713bfe28fceab47e2e00da61060b6e4 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 10:26:37 +0000
Subject: [PATCH 01/18] build: Rename -Dgtk_doc option to -Ddocumentation

Because the documentation is no longer built using gtk-doc.

Keep the old option around, but deprecated.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 .gitlab-ci.yml                  |  4 ++--
 docs/reference/glib/building.md | 12 ++++--------
 docs/reference/glib/meson.build |  2 +-
 docs/reference/meson.build      |  2 +-
 meson.build                     |  2 +-
 meson_options.txt               |  8 +++++++-
 6 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index b0415eefc..e740eae01 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -119,7 +119,7 @@ fedora-x86_64:
             -Dsystemtap=true
             -Ddtrace=true
             -Dinstalled_tests=true
-            -Dgtk_doc=true
+            -Ddocumentation=true
             _build
     - meson compile -C _build
     - mkdir -p _coverage
@@ -735,7 +735,7 @@ dist-job:
     - git submodule update --init
     - for m in $(git submodule foreach -q 'echo $path'); do git config --global --add safe.directory "${PWD}/${m}"; done
     - meson subprojects download
-    - meson setup ${MESON_COMMON_OPTIONS} --buildtype release -Dgtk_doc=true -Dman=true _build
+    - meson setup ${MESON_COMMON_OPTIONS} --buildtype release -Ddocumentation=true -Dman=true _build
     - meson dist -C _build
     - ninja -C _build glib-doc gobject-doc gio-doc
     - tar -c -J -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/glib html
diff --git a/docs/reference/glib/building.md b/docs/reference/glib/building.md
index c2c04021b..450227ab4 100644
--- a/docs/reference/glib/building.md
+++ b/docs/reference/glib/building.md
@@ -117,7 +117,7 @@ libraries.
   gobject-introspection against this copy of GLib, then re-building GLib against
   the new gobject-introspection with `-Dintrospection=enabled`. The GLib API
   documentation can be built during this second build process if
-  `-Dgtk_doc=true` is also set.
+  `-Ddocumentation=true` is also set.
 
 ## Extra Configuration Options
 
@@ -142,13 +142,9 @@ configuring the GLib library:
   Therefore, it may make sense to turn this feature off in some
   situations. The `-Dbsymbolic_functions=false` option allows to do that.
 
-`-Dgtk_doc=false` and `-Dgtk_doc=true`
-: By default, GLib will detect whether the gtk-doc package is installed.
-  If it is, then it will use it to extract and build the documentation
-  for the GLib library. These options can be used to explicitly control
-  whether gtk-doc should be used or not. If it is not used, the
-  distributed, pre-generated HTML files will be installed instead of
-  building them on your machine.
+`-Ddocumentation=false` and `-Ddocumentation=true`
+: By default, GLib will not build documentation for the library and tools. This
+  option can be used to enable building the documentation.
 
 `-Dman=false` and `-Dman=true`
 : By default, GLib will detect whether `xsltproc` and the necessary DocBook
diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build
index 3759c2ba7..303404cf6 100644
--- a/docs/reference/glib/meson.build
+++ b/docs/reference/glib/meson.build
@@ -11,7 +11,7 @@ if get_option('man')
   endforeach
 endif
 
-if get_option('gtk_doc')
+if get_option('documentation')
   # GVariant specification is currently standalone
   rst2html5 = find_program('rst2html5', 'rst2html5.py', required: false)
 
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index e7f3b3f9c..9f52de48d 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,4 +1,4 @@
-if get_option('gtk_doc') and enable_gir
+if get_option('documentation') and enable_gir
   gidocgen_dep = dependency('gi-docgen', version: '>= 2023.1',
                           fallback: ['gi-docgen', 'dummy_dep'],
                           required: true)
diff --git a/meson.build b/meson.build
index b87a95e02..0a51fae99 100644
--- a/meson.build
+++ b/meson.build
@@ -2638,7 +2638,7 @@ summary({
   'dtrace' : get_option('dtrace'),
   'systemtap' : enable_systemtap,
   'sysprof' : libsysprof_capture_dep.found(),
-  'gtk_doc' : get_option('gtk_doc'),
+  'documentation' : get_option('documentation'),
   'bsymbolic_functions' : get_option('bsymbolic_functions'),
   'force_posix_threads' : get_option('force_posix_threads'),
   'tests' : get_option('tests'),
diff --git a/meson_options.txt b/meson_options.txt
index e448748cd..83ede7fd4 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -62,10 +62,16 @@ option('sysprof',
        value : 'disabled',
        description : 'include tracing support for sysprof')
 
+option('documentation',
+       type : 'boolean',
+       value : false,
+       description : 'Build API reference and tools documentation')
+
 option('gtk_doc',
        type : 'boolean',
        value : false,
-       description : 'use gtk-doc to build documentation')
+       description : 'use gtk-doc to build documentation',
+       deprecated : 'documentation')
 
 option('bsymbolic_functions',
        type : 'boolean',

From 7d0140eea00e0b58798aa59f0838c1ed102db803 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 11:54:13 +0000
Subject: [PATCH 02/18] gdbusmessage: Reformat a doc comment to gi-docgen
 format
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In an attempt to make gobject-introspection stop warning about using
deprecated gtk-doc `Type:` tags.

It doesn’t work — the gobject-introspection parser is not clever enough
to notice the tag is inside a code block.

Still, a useful port.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gio/gdbusmessage.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/gio/gdbusmessage.c b/gio/gdbusmessage.c
index fa6077f86..e5703e808 100644
--- a/gio/gdbusmessage.c
+++ b/gio/gdbusmessage.c
@@ -3620,7 +3620,7 @@ _sort_keys_func (gconstpointer a,
  * The contents of the description has no ABI guarantees, the contents
  * and formatting is subject to change at any time. Typical output
  * looks something like this:
- * |[
+ * ```
  * Type:    method-call
  * Flags:   none
  * Version: 0
@@ -3633,9 +3633,9 @@ _sort_keys_func (gconstpointer a,
  * Body: ()
  * UNIX File Descriptors:
  *   (none)
- * ]|
+ * ```
  * or
- * |[
+ * ```
  * Type:    method-return
  * Flags:   no-reply-expected
  * Version: 0
@@ -3648,9 +3648,9 @@ _sort_keys_func (gconstpointer a,
  * Body: ()
  * UNIX File Descriptors:
  *   fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
- * ]|
+ * ```
  *
- * Returns: (not nullable): A string that should be freed with g_free().
+ * Returns: (not nullable): A string that should be freed with [func@GLib.free].
  *
  * Since: 2.26
  */

From 002f846312bb879ac08f7c6d1031cfa2481ba3d8 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 11:55:49 +0000
Subject: [PATCH 03/18] gio: Add some missing (scope) annotations

This removes some of the gobject-introspection warnings.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gio/gdbusnameowning.c   | 15 ++++++++++-----
 gio/gdbusnamewatching.c | 12 ++++++++----
 gio/gfile.c             |  2 +-
 3 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/gio/gdbusnameowning.c b/gio/gdbusnameowning.c
index 12b922c79..40feba2fd 100644
--- a/gio/gdbusnameowning.c
+++ b/gio/gdbusnameowning.c
@@ -509,8 +509,10 @@ connection_get_cb (GObject      *source_object,
  * @connection: a #GDBusConnection
  * @name: the well-known name to own
  * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
- * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL
- * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL
+ * @name_acquired_handler: (nullable) (scope notified): handler to invoke when
+ *   @name is acquired or %NULL
+ * @name_lost_handler: (nullable) (scope notified): handler to invoke when @name
+ *   is lost or %NULL
  * @user_data: user data to pass to handlers
  * @user_data_free_func: (nullable): function for freeing @user_data or %NULL
  *
@@ -571,9 +573,12 @@ g_bus_own_name_on_connection (GDBusConnection          *connection,
  * @bus_type: the type of bus to own a name on
  * @name: the well-known name to own
  * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
- * @bus_acquired_handler: (nullable): handler to invoke when connected to the bus of type @bus_type or %NULL
- * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL
- * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL
+ * @bus_acquired_handler: (nullable) (scope notified): handler to invoke when
+ *   connected to the bus of type @bus_type or %NULL
+ * @name_acquired_handler: (nullable) (scope notified): handler to invoke when
+ *   @name is acquired or %NULL
+ * @name_lost_handler: (nullable) (scope notified): handler to invoke when @name
+ *   is lost or %NULL
  * @user_data: user data to pass to handlers
  * @user_data_free_func: (nullable): function for freeing @user_data or %NULL
  *
diff --git a/gio/gdbusnamewatching.c b/gio/gdbusnamewatching.c
index 40229f92b..c86051c72 100644
--- a/gio/gdbusnamewatching.c
+++ b/gio/gdbusnamewatching.c
@@ -564,8 +564,10 @@ connection_get_cb (GObject      *source_object,
  * @bus_type: The type of bus to watch a name on.
  * @name: The name (well-known or unique) to watch.
  * @flags: Flags from the #GBusNameWatcherFlags enumeration.
- * @name_appeared_handler: (nullable): Handler to invoke when @name is known to exist or %NULL.
- * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL.
+ * @name_appeared_handler: (nullable) (scope notified): Handler to invoke when
+ *   @name is known to exist or %NULL.
+ * @name_vanished_handler: (nullable) (scope notified): Handler to invoke when
+ *   @name is known to not exist or %NULL.
  * @user_data: User data to pass to handlers.
  * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL.
  *
@@ -653,8 +655,10 @@ g_bus_watch_name (GBusType                  bus_type,
  * @connection: A #GDBusConnection.
  * @name: The name (well-known or unique) to watch.
  * @flags: Flags from the #GBusNameWatcherFlags enumeration.
- * @name_appeared_handler: (nullable): Handler to invoke when @name is known to exist or %NULL.
- * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL.
+ * @name_appeared_handler: (nullable) (scope notified): Handler to invoke when
+ *   @name is known to exist or %NULL.
+ * @name_vanished_handler: (nullable) (scope notified): Handler to invoke when
+ *   @name is known to not exist or %NULL.
  * @user_data: User data to pass to handlers.
  * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL.
  *
diff --git a/gio/gfile.c b/gio/gfile.c
index a91346d32..4527f9721 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -8825,7 +8825,7 @@ g_file_real_measure_disk_usage_finish (GFile         *file,
  * @file: a #GFile
  * @flags: #GFileMeasureFlags
  * @cancellable: (nullable): optional #GCancellable
- * @progress_callback: (nullable): a #GFileMeasureProgressCallback
+ * @progress_callback: (nullable) (scope call): a #GFileMeasureProgressCallback
  * @progress_data: user_data for @progress_callback
  * @disk_usage: (out) (optional): the number of bytes of disk space used
  * @num_dirs: (out) (optional): the number of directories encountered

From d71d4507b857129e2228f681c814867df6208f7a Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 11:56:16 +0000
Subject: [PATCH 04/18] gfileinfo: Drop an incorrect (transfer) annotation

This fixes a g-ir-scanner warning.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gio/gfileinfo.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c
index 127532a6b..d2bab923a 100644
--- a/gio/gfileinfo.c
+++ b/gio/gfileinfo.c
@@ -762,7 +762,7 @@ g_file_info_remove_attribute (GFileInfo  *info,
  *
  * Gets the attribute type, value and status for an attribute key.
  *
- * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
+ * Returns: %TRUE if @info has an attribute named @attribute,
  *      %FALSE otherwise.
  */
 gboolean

From 2a8b0c2388da0c1cfaa606afcef7691b877ad645 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 11:56:46 +0000
Subject: [PATCH 05/18] gicon: Fix an invalid introspection annotation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`(hash)` is not an annotation — it’s probably a typo for `(virtual
hash)`.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gio/gicon.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gio/gicon.c b/gio/gicon.c
index f79a77a94..4031a7b30 100644
--- a/gio/gicon.c
+++ b/gio/gicon.c
@@ -83,7 +83,7 @@ g_icon_default_init (GIconInterface *iface)
 }
 
 /**
- * g_icon_hash: (hash)
+ * g_icon_hash: (virtual hash)
  * @icon: (not nullable) (type Gio.Icon): #gconstpointer to an icon object.
  * 
  * Gets a hash for an icon.

From f50ef45220abea602157199d573c8bc12b0ba797 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 11:57:20 +0000
Subject: [PATCH 06/18] gnetworking: Hide POSIX networking symbols from
 g-ir-scanner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

They’re not part of the GLib API and don’t need to be exposed to the
scanner.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gio/gnetworking.h.in | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/gio/gnetworking.h.in b/gio/gnetworking.h.in
index 3561239f8..3dddd9024 100644
--- a/gio/gnetworking.h.in
+++ b/gio/gnetworking.h.in
@@ -49,6 +49,8 @@
 #include <arpa/nameser.h>
 @NAMESER_COMPAT_INCLUDE@
 
+#ifndef __GI_SCANNER__
+
 #ifndef T_SRV
 #define T_SRV 33
 #endif
@@ -71,6 +73,8 @@
 #endif
 #endif
 
+#endif  /* !__GI_SCANNER__ */
+
 G_BEGIN_DECLS
 
 GIO_AVAILABLE_IN_2_36

From 045186a6f235cbe9b1bac6e397a109b245483462 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 11:57:54 +0000
Subject: [PATCH 07/18] gthreadedresolver: Mark internal functions as private

This removes a few more g-ir-scanner warnings.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gio/gthreadedresolver.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/gio/gthreadedresolver.h b/gio/gthreadedresolver.h
index 099df5b84..b5556d1a1 100644
--- a/gio/gthreadedresolver.h
+++ b/gio/gthreadedresolver.h
@@ -41,6 +41,7 @@ G_DECLARE_FINAL_TYPE (GThreadedResolver, g_threaded_resolver, G, THREADED_RESOLV
 
 /* Used for a private test API */
 #ifdef G_OS_UNIX
+/*< private >*/
 GIO_AVAILABLE_IN_ALL
 GList *g_resolver_records_from_res_query (const gchar      *rrname,
                                           gint              rrtype,
@@ -48,6 +49,7 @@ GList *g_resolver_records_from_res_query (const gchar      *rrname,
                                           gssize            len,
                                           gint              herr,
                                           GError          **error);
+/*< private >*/
 GIO_AVAILABLE_IN_ALL
 gint g_resolver_record_type_to_rrtype (GResolverRecordType type);
 #endif

From d930b9058fd0f68945c834f8047c1e0a3dc98bbd Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 11:58:16 +0000
Subject: [PATCH 08/18] gtlspassword: Add a missing (out) annotation

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gio/gtlspassword.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gio/gtlspassword.c b/gio/gtlspassword.c
index f64a658ff..efb52cd2e 100644
--- a/gio/gtlspassword.c
+++ b/gio/gtlspassword.c
@@ -236,7 +236,7 @@ g_tls_password_new (GTlsPasswordFlags  flags,
 /**
  * g_tls_password_get_value: (virtual get_value)
  * @password: a #GTlsPassword object
- * @length: (optional): location to place the length of the password.
+ * @length: (optional) (out caller-allocates): location to place the length of the password.
  *
  * Get the password value. If @length is not %NULL then it will be
  * filled in with the length of the password value. (Note that the

From d07c59ed4e50bc08325c89fe74871e028fcf1eee Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 11:59:47 +0000
Subject: [PATCH 09/18] glib: Add (scope call) to a load of sort/equal
 callbacks

This fixes a load of g-ir-scanner warnings.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 glib/deprecated/gcache.c             |  4 ++--
 glib/deprecated/gthread-deprecated.c |  2 +-
 glib/garray.c                        |  4 ++--
 glib/gasyncqueue.c                   |  8 ++++----
 glib/ghash.c                         |  8 ++++----
 glib/ghook.c                         |  8 ++++----
 glib/glist.c                         | 14 +++++++-------
 glib/gnode.c                         |  8 ++++----
 glib/gqsort.c                        |  2 +-
 glib/gqueue.c                        |  8 ++++----
 glib/gregex.c                        |  2 +-
 glib/gscanner.c                      |  2 +-
 glib/gsequence.c                     | 24 ++++++++++++------------
 glib/gslist.c                        | 14 +++++++-------
 glib/gtree.c                         | 10 +++++-----
 15 files changed, 59 insertions(+), 59 deletions(-)

diff --git a/glib/deprecated/gcache.c b/glib/deprecated/gcache.c
index a045b31a6..d7da83c30 100644
--- a/glib/deprecated/gcache.c
+++ b/glib/deprecated/gcache.c
@@ -300,7 +300,7 @@ g_cache_remove (GCache        *cache,
 /**
  * g_cache_key_foreach:
  * @cache: a #GCache
- * @func: the function to call with each #GCache key
+ * @func: (scope call): the function to call with each #GCache key
  * @user_data: user data to pass to the function
  *
  * Calls the given function for each of the keys in the #GCache.
@@ -326,7 +326,7 @@ g_cache_key_foreach (GCache   *cache,
 /**
  * g_cache_value_foreach:
  * @cache: a #GCache
- * @func: the function to call with each #GCache value
+ * @func: (scope call): the function to call with each #GCache value
  * @user_data: user data to pass to the function
  *
  * Calls the given function for each of the values in the #GCache.
diff --git a/glib/deprecated/gthread-deprecated.c b/glib/deprecated/gthread-deprecated.c
index 432f026df..ec0f1a7f3 100644
--- a/glib/deprecated/gthread-deprecated.c
+++ b/glib/deprecated/gthread-deprecated.c
@@ -221,7 +221,7 @@ g_thread_set_priority (GThread         *thread,
 
 /**
  * g_thread_foreach:
- * @thread_func: function to call for all #GThread structures
+ * @thread_func: (scope call): function to call for all #GThread structures
  * @user_data: second argument to @thread_func
  *
  * Call @thread_func on all #GThreads that have been
diff --git a/glib/garray.c b/glib/garray.c
index e84c261ff..2cd750494 100644
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -2980,7 +2980,7 @@ g_byte_array_remove_range (GByteArray *array,
 /**
  * g_byte_array_sort:
  * @array: a #GByteArray
- * @compare_func: comparison function
+ * @compare_func: (scope call): comparison function
  *
  * Sorts a byte array, using @compare_func which should be a
  * qsort()-style comparison function (returns less than zero for first
@@ -3003,7 +3003,7 @@ g_byte_array_sort (GByteArray   *array,
 /**
  * g_byte_array_sort_with_data:
  * @array: a #GByteArray
- * @compare_func: comparison function
+ * @compare_func: (scope call): comparison function
  * @user_data: data to pass to @compare_func
  *
  * Like g_byte_array_sort(), but the comparison function takes an extra
diff --git a/glib/gasyncqueue.c b/glib/gasyncqueue.c
index 023288d08..8bb02793b 100644
--- a/glib/gasyncqueue.c
+++ b/glib/gasyncqueue.c
@@ -276,7 +276,7 @@ g_async_queue_push_unlocked (GAsyncQueue *queue,
  * g_async_queue_push_sorted:
  * @queue: a #GAsyncQueue
  * @data: (not nullable): the @data to push into the @queue
- * @func: the #GCompareDataFunc is used to sort @queue
+ * @func: (scope call): the #GCompareDataFunc is used to sort @queue
  * @user_data: user data passed to @func.
  *
  * Inserts @data into @queue using @func to determine the new
@@ -317,7 +317,7 @@ g_async_queue_invert_compare (gpointer  v1,
  * g_async_queue_push_sorted_unlocked:
  * @queue: a #GAsyncQueue
  * @data: the data to push into the @queue
- * @func: the #GCompareDataFunc is used to sort @queue
+ * @func: (scope call): the #GCompareDataFunc is used to sort @queue
  * @user_data: user data passed to @func.
  *
  * Inserts @data into @queue using @func to determine the new
@@ -672,7 +672,7 @@ g_async_queue_length_unlocked (GAsyncQueue *queue)
 /**
  * g_async_queue_sort:
  * @queue: a #GAsyncQueue
- * @func: the #GCompareDataFunc is used to sort @queue
+ * @func: (scope call): the #GCompareDataFunc is used to sort @queue
  * @user_data: user data passed to @func
  *
  * Sorts @queue using @func.
@@ -716,7 +716,7 @@ g_async_queue_sort (GAsyncQueue      *queue,
 /**
  * g_async_queue_sort_unlocked:
  * @queue: a #GAsyncQueue
- * @func: the #GCompareDataFunc is used to sort @queue
+ * @func: (scope call): the #GCompareDataFunc is used to sort @queue
  * @user_data: user data passed to @func
  *
  * Sorts @queue using @func.
diff --git a/glib/ghash.c b/glib/ghash.c
index 90e03bf9f..2f626e9f8 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -2019,7 +2019,7 @@ g_hash_table_foreach_remove_or_steal (GHashTable *hash_table,
 /**
  * g_hash_table_foreach_remove:
  * @hash_table: a #GHashTable
- * @func: the function to call for each key/value pair
+ * @func: (scope call): the function to call for each key/value pair
  * @user_data: user data to pass to the function
  *
  * Calls the given function for each key/value pair in the
@@ -2047,7 +2047,7 @@ g_hash_table_foreach_remove (GHashTable *hash_table,
 /**
  * g_hash_table_foreach_steal:
  * @hash_table: a #GHashTable
- * @func: the function to call for each key/value pair
+ * @func: (scope call): the function to call for each key/value pair
  * @user_data: user data to pass to the function
  *
  * Calls the given function for each key/value pair in the
@@ -2074,7 +2074,7 @@ g_hash_table_foreach_steal (GHashTable *hash_table,
 /**
  * g_hash_table_foreach:
  * @hash_table: a #GHashTable
- * @func: the function to call for each key/value pair
+ * @func: (scope call): the function to call for each key/value pair
  * @user_data: user data to pass to the function
  *
  * Calls the given function for each of the key/value pairs in the
@@ -2125,7 +2125,7 @@ g_hash_table_foreach (GHashTable *hash_table,
 /**
  * g_hash_table_find:
  * @hash_table: a #GHashTable
- * @predicate: function to test the key/value pairs for a certain property
+ * @predicate: (scope call): function to test the key/value pairs for a certain property
  * @user_data: user data to pass to the function
  *
  * Calls the given function for key/value pairs in the #GHashTable
diff --git a/glib/ghook.c b/glib/ghook.c
index c2de46943..2c38dbca6 100644
--- a/glib/ghook.c
+++ b/glib/ghook.c
@@ -587,7 +587,7 @@ g_hook_list_invoke_check (GHookList *hook_list,
  * @may_recurse: %TRUE if hooks which are currently running
  *     (e.g. in another thread) are considered valid. If set to %FALSE,
  *     these are skipped
- * @marshaller: the function to call for each #GHook
+ * @marshaller: (scope call): the function to call for each #GHook
  * @marshal_data: data to pass to @marshaller
  *
  * Calls a function on each valid #GHook and destroys it if the
@@ -637,7 +637,7 @@ g_hook_list_marshal_check (GHookList	       *hook_list,
  * @may_recurse: %TRUE if hooks which are currently running
  *     (e.g. in another thread) are considered valid. If set to %FALSE,
  *     these are skipped
- * @marshaller: the function to call for each #GHook
+ * @marshaller: (scope call): the function to call for each #GHook
  * @marshal_data: data to pass to @marshaller
  *
  * Calls a function on each valid #GHook.
@@ -795,7 +795,7 @@ g_hook_get (GHookList *hook_list,
  * @hook_list: a #GHookList
  * @need_valids: %TRUE if #GHook elements which have been destroyed
  *     should be skipped
- * @func: the function to call for each #GHook, which should return
+ * @func: (scope call): the function to call for each #GHook, which should return
  *     %TRUE when the #GHook has been found
  * @data: the data to pass to @func
  *
@@ -972,7 +972,7 @@ g_hook_find_func_data (GHookList *hook_list,
  * g_hook_insert_sorted:
  * @hook_list: a #GHookList
  * @hook: the #GHook to insert
- * @func: the comparison function used to sort the #GHook elements
+ * @func: (scope call): the comparison function used to sort the #GHook elements
  *
  * Inserts a #GHook into a #GHookList, sorted by the given function.
  */
diff --git a/glib/glist.c b/glib/glist.c
index fc826dbd0..d56ff7ceb 100644
--- a/glib/glist.c
+++ b/glib/glist.c
@@ -634,7 +634,7 @@ g_list_copy (GList *list)
 /**
  * g_list_copy_deep:
  * @list: a #GList, this must point to the top of the list
- * @func: a copy function used to copy every element in the list
+ * @func: (scope call): a copy function used to copy every element in the list
  * @user_data: user data passed to the copy function @func, or %NULL
  *
  * Makes a full (deep) copy of a #GList.
@@ -821,7 +821,7 @@ g_list_find (GList         *list,
  * g_list_find_custom:
  * @list: a #GList, this must point to the top of the list
  * @data: user data passed to the function
- * @func: the function to call for each element. 
+ * @func: (scope call): the function to call for each element.
  *     It should return 0 when the desired element is found
  *
  * Finds an element in a #GList, using a supplied function to 
@@ -981,7 +981,7 @@ g_list_length (GList *list)
 /**
  * g_list_foreach:
  * @list: a #GList, this must point to the top of the list
- * @func: the function to call with each element's data
+ * @func: (scope call): the function to call with each element's data
  * @user_data: user data to pass to the function
  *
  * Calls a function for each element of a #GList.
@@ -1067,7 +1067,7 @@ g_list_insert_sorted_real (GList    *list,
  * @list: a pointer to a #GList, this must point to the top of the
  *     already sorted list
  * @data: the data for the new element
- * @func: the function to compare elements in the list. It should 
+ * @func: (scope call): the function to compare elements in the list. It should
  *     return a number > 0 if the first parameter comes after the 
  *     second parameter in the sort order.
  *
@@ -1094,7 +1094,7 @@ g_list_insert_sorted (GList        *list,
  * @list: a pointer to a #GList, this must point to the top of the
  *     already sorted list
  * @data: the data for the new element
- * @func: the function to compare elements in the list. It should
+ * @func: (scope call): the function to compare elements in the list. It should
  *     return a number > 0 if the first parameter  comes after the
  *     second parameter in the sort order.
  * @user_data: user data to pass to comparison function
@@ -1189,7 +1189,7 @@ g_list_sort_real (GList    *list,
 /**
  * g_list_sort:
  * @list: a #GList, this must point to the top of the list
- * @compare_func: the comparison function used to sort the #GList.
+ * @compare_func: (scope call): the comparison function used to sort the #GList.
  *     This function is passed the data from 2 elements of the #GList 
  *     and should return 0 if they are equal, a negative value if the 
  *     first element comes before the second, or a positive value if 
@@ -1223,7 +1223,7 @@ g_list_sort (GList        *list,
 /**
  * g_list_sort_with_data:
  * @list: a #GList, this must point to the top of the list
- * @compare_func: comparison function
+ * @compare_func: (scope call): comparison function
  * @user_data: user data to pass to comparison function
  *
  * Like g_list_sort(), but the comparison function accepts 
diff --git a/glib/gnode.c b/glib/gnode.c
index e07f126d0..8e0187f88 100644
--- a/glib/gnode.c
+++ b/glib/gnode.c
@@ -133,8 +133,8 @@ g_node_unlink (GNode *node)
 /**
  * g_node_copy_deep:
  * @node: a #GNode
- * @copy_func: the function which is called to copy the data inside each node,
- *   or %NULL to use the original data.
+ * @copy_func: (scope call): the function which is called to copy the data
+ *   inside each node, or %NULL to use the original data.
  * @data: data to pass to @copy_func
  * 
  * Recursively copies a #GNode and its data.
@@ -775,7 +775,7 @@ g_node_depth_traverse_level (GNode             *node,
  *     depth will not be visited. If max_depth is -1 all nodes in 
  *     the tree are visited. If depth is 1, only the root is visited. 
  *     If depth is 2, the root and its children are visited. And so on.
- * @func: the function to call for each visited #GNode
+ * @func: (scope call): the function to call for each visited #GNode
  * @data: user data to pass to the function
  *
  * Traverses a tree starting at the given root #GNode.
@@ -1198,7 +1198,7 @@ g_node_last_sibling (GNode *node)
  * @node: a #GNode
  * @flags: which types of children are to be visited, one of 
  *     %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
- * @func: the function to call for each visited node
+ * @func: (scope call): the function to call for each visited node
  * @data: user data to pass to the function
  *
  * Calls a function for each of the children of a #GNode. Note that it
diff --git a/glib/gqsort.c b/glib/gqsort.c
index a0edcd4d9..9d6bb1e14 100644
--- a/glib/gqsort.c
+++ b/glib/gqsort.c
@@ -286,7 +286,7 @@ msort_r (void *b, size_t n, size_t s, GCompareDataFunc cmp, void *arg)
  * @pbase: (not nullable): start of array to sort
  * @total_elems: elements in the array
  * @size: size of each element
- * @compare_func: function to compare elements
+ * @compare_func: (scope call): function to compare elements
  * @user_data: data to pass to @compare_func
  *
  * This is just like the standard C qsort() function, but
diff --git a/glib/gqueue.c b/glib/gqueue.c
index 83fbafee9..07805ff27 100644
--- a/glib/gqueue.c
+++ b/glib/gqueue.c
@@ -227,7 +227,7 @@ g_queue_copy (GQueue *queue)
 /**
  * g_queue_foreach:
  * @queue: a #GQueue
- * @func: the function to call for each element's data
+ * @func: (scope call): the function to call for each element's data
  * @user_data: user data to pass to @func
  * 
  * Calls @func for each element in the queue passing @user_data to the
@@ -281,7 +281,7 @@ g_queue_find (GQueue        *queue,
  * g_queue_find_custom:
  * @queue: a #GQueue
  * @data: user data passed to @func
- * @func: a #GCompareFunc to call for each element. It should return 0
+ * @func: (scope call): a #GCompareFunc to call for each element. It should return 0
  *     when the desired element is found
  *
  * Finds an element in a #GQueue, using a supplied function to find the
@@ -308,7 +308,7 @@ g_queue_find_custom (GQueue        *queue,
 /**
  * g_queue_sort:
  * @queue: a #GQueue
- * @compare_func: the #GCompareDataFunc used to sort @queue. This function
+ * @compare_func: (scope call): the #GCompareDataFunc used to sort @queue. This function
  *     is passed two elements of the queue and should return 0 if they are
  *     equal, a negative value if the first comes before the second, and
  *     a positive value if the second comes before the first.
@@ -1121,7 +1121,7 @@ g_queue_insert_after_link (GQueue   *queue,
  * g_queue_insert_sorted:
  * @queue: a #GQueue
  * @data: the data to insert
- * @func: the #GCompareDataFunc used to compare elements in the queue. It is
+ * @func: (scope call): the #GCompareDataFunc used to compare elements in the queue. It is
  *     called with two elements of the @queue and @user_data. It should
  *     return 0 if the elements are equal, a negative value if the first
  *     element comes before the second, and a positive value if the second
diff --git a/glib/gregex.c b/glib/gregex.c
index ae1cec1b0..466abfba0 100644
--- a/glib/gregex.c
+++ b/glib/gregex.c
@@ -3376,7 +3376,7 @@ g_regex_replace_literal (const GRegex      *regex,
  * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated
  * @start_position: starting index of the string to match, in bytes
  * @match_options: options for the match
- * @eval: a function to call for each match
+ * @eval: (scope call): a function to call for each match
  * @user_data: user data to pass to the function
  * @error: location to store the error occurring, or %NULL to ignore errors
  *
diff --git a/glib/gscanner.c b/glib/gscanner.c
index 14125f3fc..cb7e811da 100644
--- a/glib/gscanner.c
+++ b/glib/gscanner.c
@@ -895,7 +895,7 @@ g_scanner_foreach_internal (gpointer  _key,
  * g_scanner_scope_foreach_symbol:
  * @scanner: a #GScanner
  * @scope_id: the scope id
- * @func: the function to call for each symbol/value pair
+ * @func: (scope call): the function to call for each symbol/value pair
  * @user_data: user data to pass to the function
  *
  * Calls the given function for each of the symbol/value pairs
diff --git a/glib/gsequence.c b/glib/gsequence.c
index 06f1cbe91..81f0d085a 100644
--- a/glib/gsequence.c
+++ b/glib/gsequence.c
@@ -255,7 +255,7 @@ g_sequence_free (GSequence *seq)
  * g_sequence_foreach_range:
  * @begin: a #GSequenceIter
  * @end: a #GSequenceIter
- * @func: a #GFunc
+ * @func: (scope call): a #GFunc
  * @user_data: user data passed to @func
  *
  * Calls @func for each item in the range (@begin, @end) passing
@@ -297,7 +297,7 @@ g_sequence_foreach_range (GSequenceIter *begin,
 /**
  * g_sequence_foreach:
  * @seq: a #GSequence
- * @func: the function to call for each item in @seq
+ * @func: (scope call): the function to call for each item in @seq
  * @user_data: user data passed to @func
  *
  * Calls @func for each item in the sequence passing @user_data
@@ -627,7 +627,7 @@ g_sequence_move_range (GSequenceIter *dest,
 /**
  * g_sequence_sort:
  * @seq: a #GSequence
- * @cmp_func: the function used to sort the sequence
+ * @cmp_func: (scope call): the function used to sort the sequence
  * @cmp_data: user data passed to @cmp_func
  *
  * Sorts @seq using @cmp_func.
@@ -659,7 +659,7 @@ g_sequence_sort (GSequence        *seq,
  * g_sequence_insert_sorted:
  * @seq: a #GSequence
  * @data: the data to insert
- * @cmp_func: the function used to compare items in the sequence
+ * @cmp_func: (scope call): the function used to compare items in the sequence
  * @cmp_data: user data passed to @cmp_func.
  *
  * Inserts @data into @seq using @cmp_func to determine the new
@@ -701,7 +701,7 @@ g_sequence_insert_sorted (GSequence        *seq,
 /**
  * g_sequence_sort_changed:
  * @iter: A #GSequenceIter
- * @cmp_func: the function used to compare items in the sequence
+ * @cmp_func: (scope call): the function used to compare items in the sequence
  * @cmp_data: user data passed to @cmp_func.
  *
  * Moves the data pointed to by @iter to a new position as indicated by
@@ -742,7 +742,7 @@ g_sequence_sort_changed (GSequenceIter    *iter,
  * g_sequence_search:
  * @seq: a #GSequence
  * @data: data for the new item
- * @cmp_func: the function used to compare items in the sequence
+ * @cmp_func: (scope call): the function used to compare items in the sequence
  * @cmp_data: user data passed to @cmp_func
  *
  * Returns an iterator pointing to the position where @data would
@@ -786,7 +786,7 @@ g_sequence_search (GSequence        *seq,
  * g_sequence_lookup:
  * @seq: a #GSequence
  * @data: data to look up
- * @cmp_func: the function used to compare items in the sequence
+ * @cmp_func: (scope call): the function used to compare items in the sequence
  * @cmp_data: user data passed to @cmp_func
  *
  * Returns an iterator pointing to the position of the first item found
@@ -830,7 +830,7 @@ g_sequence_lookup (GSequence        *seq,
 /**
  * g_sequence_sort_iter:
  * @seq: a #GSequence
- * @cmp_func: the function used to compare iterators in the sequence
+ * @cmp_func: (scope call): the function used to compare iterators in the sequence
  * @cmp_data: user data passed to @cmp_func
  *
  * Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead
@@ -884,7 +884,7 @@ g_sequence_sort_iter (GSequence                *seq,
 /**
  * g_sequence_sort_changed_iter:
  * @iter: a #GSequenceIter
- * @iter_cmp: the function used to compare iterators in the sequence
+ * @iter_cmp: (scope call): the function used to compare iterators in the sequence
  * @cmp_data: user data passed to @cmp_func
  *
  * Like g_sequence_sort_changed(), but uses
@@ -949,7 +949,7 @@ g_sequence_sort_changed_iter (GSequenceIter            *iter,
  * g_sequence_insert_sorted_iter:
  * @seq: a #GSequence
  * @data: data for the new item
- * @iter_cmp: the function used to compare iterators in the sequence
+ * @iter_cmp: (scope call): the function used to compare iterators in the sequence
  * @cmp_data: user data passed to @iter_cmp
  *
  * Like g_sequence_insert_sorted(), but uses
@@ -1016,7 +1016,7 @@ g_sequence_insert_sorted_iter (GSequence                *seq,
  * g_sequence_search_iter:
  * @seq: a #GSequence
  * @data: data for the new item
- * @iter_cmp: the function used to compare iterators in the sequence
+ * @iter_cmp: (scope call): the function used to compare iterators in the sequence
  * @cmp_data: user data passed to @iter_cmp
  *
  * Like g_sequence_search(), but uses a #GSequenceIterCompareFunc
@@ -1074,7 +1074,7 @@ g_sequence_search_iter (GSequence                *seq,
  * g_sequence_lookup_iter:
  * @seq: a #GSequence
  * @data: data to look up
- * @iter_cmp: the function used to compare iterators in the sequence
+ * @iter_cmp: (scope call): the function used to compare iterators in the sequence
  * @cmp_data: user data passed to @iter_cmp
  *
  * Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc
diff --git a/glib/gslist.c b/glib/gslist.c
index 9520662bd..68c0e4074 100644
--- a/glib/gslist.c
+++ b/glib/gslist.c
@@ -521,7 +521,7 @@ g_slist_copy (GSList *list)
 /**
  * g_slist_copy_deep:
  * @list: a #GSList
- * @func: a copy function used to copy every element in the list
+ * @func: (scope call): a copy function used to copy every element in the list
  * @user_data: user data passed to the copy function @func, or #NULL
  *
  * Makes a full (deep) copy of a #GSList.
@@ -677,7 +677,7 @@ g_slist_find (GSList        *list,
  * g_slist_find_custom:
  * @list: a #GSList
  * @data: user data passed to the function
- * @func: the function to call for each element.
+ * @func: (scope call): the function to call for each element.
  *     It should return 0 when the desired element is found
  *
  * Finds an element in a #GSList, using a supplied function to
@@ -817,7 +817,7 @@ g_slist_length (GSList *list)
 /**
  * g_slist_foreach:
  * @list: a #GSList
- * @func: the function to call with each element's data
+ * @func: (scope call): the function to call with each element's data
  * @user_data: user data to pass to the function
  *
  * Calls a function for each element of a #GSList.
@@ -896,7 +896,7 @@ g_slist_insert_sorted_real (GSList   *list,
  * g_slist_insert_sorted:
  * @list: a #GSList
  * @data: the data for the new element
- * @func: the function to compare elements in the list.
+ * @func: (scope call): the function to compare elements in the list.
  *     It should return a number > 0 if the first parameter
  *     comes after the second parameter in the sort order.
  *
@@ -917,7 +917,7 @@ g_slist_insert_sorted (GSList       *list,
  * g_slist_insert_sorted_with_data:
  * @list: a #GSList
  * @data: the data for the new element
- * @func: the function to compare elements in the list.
+ * @func: (scope call): the function to compare elements in the list.
  *     It should return a number > 0 if the first parameter
  *     comes after the second parameter in the sort order.
  * @user_data: data to pass to comparison function
@@ -1002,7 +1002,7 @@ g_slist_sort_real (GSList   *list,
 /**
  * g_slist_sort:
  * @list: a #GSList
- * @compare_func: the comparison function used to sort the #GSList.
+ * @compare_func: (scope call): the comparison function used to sort the #GSList.
  *     This function is passed the data from 2 elements of the #GSList
  *     and should return 0 if they are equal, a negative value if the
  *     first element comes before the second, or a positive value if
@@ -1023,7 +1023,7 @@ g_slist_sort (GSList       *list,
 /**
  * g_slist_sort_with_data:
  * @list: a #GSList
- * @compare_func: comparison function
+ * @compare_func: (scope call): comparison function
  * @user_data: data to pass to comparison function
  *
  * Like g_slist_sort(), but the sort function accepts a user data argument.
diff --git a/glib/gtree.c b/glib/gtree.c
index f7b6fce22..b8d387737 100644
--- a/glib/gtree.c
+++ b/glib/gtree.c
@@ -1106,7 +1106,7 @@ g_tree_lookup_extended (GTree         *tree,
 /**
  * g_tree_foreach:
  * @tree: a #GTree
- * @func: the function to call for each node visited.
+ * @func: (scope call): the function to call for each node visited.
  *     If this function returns %TRUE, the traversal is stopped.
  * @user_data: user data to pass to the function
  *
@@ -1145,7 +1145,7 @@ g_tree_foreach (GTree         *tree,
 /**
  * g_tree_foreach_node:
  * @tree: a #GTree
- * @func: the function to call for each node visited.
+ * @func: (scope call): the function to call for each node visited.
  *     If this function returns %TRUE, the traversal is stopped.
  * @user_data: user data to pass to the function
  *
@@ -1186,7 +1186,7 @@ g_tree_foreach_node (GTree             *tree,
 /**
  * g_tree_traverse:
  * @tree: a #GTree
- * @traverse_func: the function to call for each node visited. If this 
+ * @traverse_func: (scope call): the function to call for each node visited. If this
  *   function returns %TRUE, the traversal is stopped.
  * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
  *   %G_PRE_ORDER and %G_POST_ORDER
@@ -1246,7 +1246,7 @@ g_tree_traverse (GTree         *tree,
 /**
  * g_tree_search_node:
  * @tree: a #GTree
- * @search_func: a function used to search the #GTree
+ * @search_func: (scope call): a function used to search the #GTree
  * @user_data: the data passed as the second argument to @search_func
  *
  * Searches a #GTree using @search_func.
@@ -1280,7 +1280,7 @@ g_tree_search_node (GTree         *tree,
 /**
  * g_tree_search:
  * @tree: a #GTree
- * @search_func: a function used to search the #GTree
+ * @search_func: (scope call): a function used to search the #GTree
  * @user_data: the data passed as the second argument to @search_func
  *
  * Searches a #GTree using @search_func.

From f14cd8de14d196091f6951c0a8201dd7fbc056e0 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:00:14 +0000
Subject: [PATCH 10/18] gcompletion: Make argument names match up

This fixes some warnings from g-ir-scanner.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 glib/deprecated/gcompletion.c | 2 +-
 glib/deprecated/gcompletion.h | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/glib/deprecated/gcompletion.c b/glib/deprecated/gcompletion.c
index 1bc9e97fd..73192894f 100644
--- a/glib/deprecated/gcompletion.c
+++ b/glib/deprecated/gcompletion.c
@@ -81,7 +81,7 @@
 
 /**
  * GCompletionFunc:
- * @Param1: the completion item.
+ * @item: the completion item.
  *
  * Specifies the type of the function passed to g_completion_new(). It
  * should return the string corresponding to the given target item.
diff --git a/glib/deprecated/gcompletion.h b/glib/deprecated/gcompletion.h
index 2be87d276..7f9f7825d 100644
--- a/glib/deprecated/gcompletion.h
+++ b/glib/deprecated/gcompletion.h
@@ -37,7 +37,7 @@ G_BEGIN_DECLS
 
 typedef struct _GCompletion     GCompletion;
 
-typedef gchar*          (*GCompletionFunc)      (gpointer);
+typedef gchar*          (*GCompletionFunc)      (gpointer item);
 
 /* GCompletion
  */

From 8f08c1a038046715306065ef036abe88cfc66f99 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:00:35 +0000
Subject: [PATCH 11/18] gthread: Make some argument names match up
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This fixes a warning from g-ir-scanner as the declaration and
documentation comment didn’t match.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 glib/deprecated/gthread.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/glib/deprecated/gthread.h b/glib/deprecated/gthread.h
index a36613691..a18a730d6 100644
--- a/glib/deprecated/gthread.h
+++ b/glib/deprecated/gthread.h
@@ -286,7 +286,7 @@ void            g_cond_free             (GCond  *cond);
 GLIB_DEPRECATED_IN_2_32
 gboolean        g_cond_timed_wait       (GCond          *cond,
                                          GMutex         *mutex,
-                                         GTimeVal       *timeval);
+                                         GTimeVal       *abs_time);
 
 G_GNUC_END_IGNORE_DEPRECATIONS
 

From c1547f62bc398cb7bf4c1084c76a46c1b1002328 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:01:12 +0000
Subject: [PATCH 12/18] gbytearray: Add missing (transfer) annotations

`GByteArray` is a bit odd in that it allows call-chaining. All the
instances of that were missing a `(transfer none)` annotation though.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 glib/garray.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/glib/garray.c b/glib/garray.c
index 2cd750494..ba109aef4 100644
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -2761,7 +2761,7 @@ g_byte_array_new_take (guint8 *data,
  * bytes to the array. Note however that the size of the array is still
  * 0.
  *
- * Returns: the new #GByteArray
+ * Returns: (transfer full): the new #GByteArray
  */
 GByteArray*
 g_byte_array_sized_new (guint reserved_size)
@@ -2825,7 +2825,7 @@ g_byte_array_free_to_bytes (GByteArray *array)
  * Atomically increments the reference count of @array by one.
  * This function is thread-safe and may be called from any thread.
  *
- * Returns: The passed in #GByteArray
+ * Returns: (transfer full): The passed in #GByteArray
  *
  * Since: 2.22
  */
@@ -2861,7 +2861,7 @@ g_byte_array_unref (GByteArray *array)
  * Adds the given bytes to the end of the #GByteArray.
  * The array will grow in size automatically if necessary.
  *
- * Returns: the #GByteArray
+ * Returns: (transfer none): the #GByteArray
  */
 GByteArray*
 g_byte_array_append (GByteArray   *array,
@@ -2882,7 +2882,7 @@ g_byte_array_append (GByteArray   *array,
  * Adds the given data to the start of the #GByteArray.
  * The array will grow in size automatically if necessary.
  *
- * Returns: the #GByteArray
+ * Returns: (transfer none): the #GByteArray
  */
 GByteArray*
 g_byte_array_prepend (GByteArray   *array,
@@ -2901,7 +2901,7 @@ g_byte_array_prepend (GByteArray   *array,
  *
  * Sets the size of the #GByteArray, expanding it if necessary.
  *
- * Returns: the #GByteArray
+ * Returns: (transfer none): the #GByteArray
  */
 GByteArray*
 g_byte_array_set_size (GByteArray *array,
@@ -2920,7 +2920,7 @@ g_byte_array_set_size (GByteArray *array,
  * Removes the byte at the given index from a #GByteArray.
  * The following bytes are moved down one place.
  *
- * Returns: the #GByteArray
+ * Returns: (transfer none): the #GByteArray
  **/
 GByteArray*
 g_byte_array_remove_index (GByteArray *array,
@@ -2941,7 +2941,7 @@ g_byte_array_remove_index (GByteArray *array,
  * does not preserve the order of the #GByteArray. But it is faster
  * than g_byte_array_remove_index().
  *
- * Returns: the #GByteArray
+ * Returns: (transfer none): the #GByteArray
  */
 GByteArray*
 g_byte_array_remove_index_fast (GByteArray *array,
@@ -2961,7 +2961,7 @@ g_byte_array_remove_index_fast (GByteArray *array,
  * Removes the given number of bytes starting at the given index from a
  * #GByteArray.  The following elements are moved to close the gap.
  *
- * Returns: the #GByteArray
+ * Returns: (transfer none): the #GByteArray
  *
  * Since: 2.4
  */

From c7dfd218eaf3495869b0349d08ae32d5cc74c5cd Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:02:04 +0000
Subject: [PATCH 13/18] gerror: Add missing (scope forever) annotations

Extended error domains can never be unregistered, so these closures
have to be around forever.

Fixes some g-ir-scanner warnings.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 glib/gerror.c | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/glib/gerror.c b/glib/gerror.c
index 392cb6ff1..25be13f8d 100644
--- a/glib/gerror.c
+++ b/glib/gerror.c
@@ -106,9 +106,9 @@ error_domain_register (GQuark            error_quark,
  * g_error_domain_register_static:
  * @error_type_name: static string to create a #GQuark from
  * @error_type_private_size: size of the private error data in bytes
- * @error_type_init: function initializing fields of the private error data
- * @error_type_copy: function copying fields of the private error data
- * @error_type_clear: function freeing fields of the private error data
+ * @error_type_init: (scope forever): function initializing fields of the private error data
+ * @error_type_copy: (scope forever): function copying fields of the private error data
+ * @error_type_clear: (scope forever): function freeing fields of the private error data
  *
  * This function registers an extended #GError domain.
  *
@@ -159,9 +159,9 @@ g_error_domain_register_static (const char        *error_type_name,
  * g_error_domain_register:
  * @error_type_name: string to create a #GQuark from
  * @error_type_private_size: size of the private error data in bytes
- * @error_type_init: function initializing fields of the private error data
- * @error_type_copy: function copying fields of the private error data
- * @error_type_clear: function freeing fields of the private error data
+ * @error_type_init: (scope forever): function initializing fields of the private error data
+ * @error_type_copy: (scope forever): function copying fields of the private error data
+ * @error_type_clear: (scope forever): function freeing fields of the private error data
  *
  * This function registers an extended #GError domain.
  * @error_type_name will be duplicated. Otherwise does the same as

From 02725b9bbd96f9df0011954f972b83a4c4969a0d Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:02:49 +0000
Subject: [PATCH 14/18] ghashtable: Add various missing (transfer) annotations

Fixes some g-ir-scanner warnings.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 glib/ghash.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/glib/ghash.c b/glib/ghash.c
index 2f626e9f8..2dcdd9dfc 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -970,7 +970,7 @@ g_hash_table_ensure_keyval_fits (GHashTable *hash_table, gpointer key, gpointer
  * as its first parameter, and the user-provided key to check against as
  * its second.
  *
- * Returns: a new #GHashTable
+ * Returns: (transfer full): a new #GHashTable
  */
 GHashTable *
 g_hash_table_new (GHashFunc  hash_func,
@@ -1003,7 +1003,7 @@ g_hash_table_new (GHashFunc  hash_func,
  * calling g_hash_table_remove_all() before releasing the last reference using
  * g_hash_table_unref().
  *
- * Returns: a new #GHashTable
+ * Returns: (transfer full): a new #GHashTable
  */
 GHashTable *
 g_hash_table_new_full (GHashFunc      hash_func,
@@ -1154,7 +1154,7 @@ g_hash_table_iter_next (GHashTableIter *iter,
  *
  * Returns the #GHashTable associated with @iter.
  *
- * Returns: the #GHashTable associated with @iter.
+ * Returns: (transfer none): the #GHashTable associated with @iter.
  *
  * Since: 2.16
  */
@@ -1398,7 +1398,7 @@ g_hash_table_iter_steal (GHashTableIter *iter)
  * Atomically increments the reference count of @hash_table by one.
  * This function is MT-safe and may be called from any thread.
  *
- * Returns: the passed in #GHashTable
+ * Returns: (transfer full): the passed in #GHashTable
  *
  * Since: 2.10
  */
@@ -1414,7 +1414,7 @@ g_hash_table_ref (GHashTable *hash_table)
 
 /**
  * g_hash_table_unref:
- * @hash_table: a valid #GHashTable
+ * @hash_table: (transfer full): a valid #GHashTable
  *
  * Atomically decrements the reference count of @hash_table by one.
  * If the reference count drops to 0, all keys and values will be

From 81d96f58988a49b2b148b46332ea85017ff9e92b Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:03:15 +0000
Subject: [PATCH 15/18] gmarkup: Add a missing (element-type) annotation

Fixes a g-ir-scanner warning.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 glib/gmarkup.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/glib/gmarkup.c b/glib/gmarkup.c
index 6c07010db..f838ab010 100644
--- a/glib/gmarkup.c
+++ b/glib/gmarkup.c
@@ -1885,7 +1885,7 @@ g_markup_parse_context_get_element (GMarkupParseContext *context)
  * would merely return the name of the element that is being
  * processed.
  *
- * Returns: the element stack, which must not be modified
+ * Returns: (element-type utf8): the element stack, which must not be modified
  *
  * Since: 2.16
  */

From 58208c4ace8651838f3d571312e941ebb6541018 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:03:34 +0000
Subject: [PATCH 16/18] gvarianttype: Add a missing argument name

To make it match its definition and documentation comment. This fixes a
g-ir-scanner warning.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 glib/gvarianttype.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/glib/gvarianttype.h b/glib/gvarianttype.h
index 2d44308fb..0fc751bcb 100644
--- a/glib/gvarianttype.h
+++ b/glib/gvarianttype.h
@@ -366,7 +366,7 @@ GVariantType *                  g_variant_type_new_dict_entry           (const G
 
 /*< private >*/
 GLIB_AVAILABLE_IN_ALL
-const GVariantType *            g_variant_type_checked_                 (const gchar *);
+const GVariantType *            g_variant_type_checked_                 (const gchar *type_string);
 GLIB_AVAILABLE_IN_2_60
 gsize                           g_variant_type_string_get_depth_        (const gchar *type_string);
 

From 47869719be3342a6fe6498a4b463cdfcb26393e5 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:04:12 +0000
Subject: [PATCH 17/18] gboxed: Add missing (scope forever) annotations

Boxed types can never be unregistered, so these closures have to be
around forever.

Fixes some g-ir-scanner warnings.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gobject/gboxed.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/gobject/gboxed.c b/gobject/gboxed.c
index 8872ca433..5a9cff85a 100644
--- a/gobject/gboxed.c
+++ b/gobject/gboxed.c
@@ -255,8 +255,8 @@ boxed_proxy_lcopy_value (const GValue *value,
 /**
  * g_boxed_type_register_static:
  * @name: Name of the new boxed type.
- * @boxed_copy: Boxed structure copy function.
- * @boxed_free: Boxed structure free function.
+ * @boxed_copy: (scope forever): Boxed structure copy function.
+ * @boxed_free: (scope forever): Boxed structure free function.
  *
  * This function creates a new %G_TYPE_BOXED derived type id for a new
  * boxed type with name @name.

From 266f570f3c4b08f2ec3fd316304e2d2b9f7ec46e Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Wed, 29 Nov 2023 12:04:59 +0000
Subject: [PATCH 18/18] gsignal: Add missing (scope forever) annotations

Signals (as opposed to signal connections) can never be unregistered, so
these closures have to be around forever.

Fixes some g-ir-scanner warnings.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 gobject/gsignal.c | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index f08729291..04456ce1d 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -1368,7 +1368,7 @@ g_signal_query (guint         signal_id,
  * @class_offset: The offset of the function pointer in the class structure
  *  for this type. Used to invoke a class method generically. Pass 0 to
  *  not associate a class method slot with this signal.
- * @accumulator: (nullable): the accumulator for this signal; may be %NULL.
+ * @accumulator: (nullable) (scope forever): the accumulator for this signal; may be %NULL.
  * @accu_data: (nullable) (closure accumulator): user data for the @accumulator.
  * @c_marshaller: (nullable): the function to translate arrays of parameter
  *  values to signal emissions into C language callback invocations or %NULL.
@@ -1441,10 +1441,10 @@ g_signal_new (const gchar	 *signal_name,
  * @signal_flags: a combination of #GSignalFlags specifying detail of when
  *  the default handler is to be invoked. You should at least specify
  *  %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
- * @class_handler: (nullable): a #GCallback which acts as class implementation of
+ * @class_handler: (nullable) (scope forever): a #GCallback which acts as class implementation of
  *  this signal. Used to invoke a class method generically. Pass %NULL to
  *  not associate a class method with this signal.
- * @accumulator: (nullable): the accumulator for this signal; may be %NULL.
+ * @accumulator: (nullable) (scope forever): the accumulator for this signal; may be %NULL.
  * @accu_data: (nullable) (closure accumulator): user data for the @accumulator.
  * @c_marshaller: (nullable): the function to translate arrays of parameter
  *  values to signal emissions into C language callback invocations or %NULL.
@@ -1581,7 +1581,7 @@ signal_add_class_closure (SignalNode *node,
  *     %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST
  * @class_closure: (nullable): The closure to invoke on signal emission;
  *     may be %NULL
- * @accumulator: (nullable): the accumulator for this signal; may be %NULL
+ * @accumulator: (nullable) (scope forever): the accumulator for this signal; may be %NULL
  * @accu_data: (nullable) (closure accumulator): user data for the @accumulator
  * @c_marshaller: (nullable): the function to translate arrays of
  *     parameter values to signal emissions into C language callback
@@ -1842,7 +1842,7 @@ g_signal_set_va_marshaller (guint              signal_id,
  *  the default handler is to be invoked. You should at least specify
  *  %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
  * @class_closure: (nullable): The closure to invoke on signal emission; may be %NULL.
- * @accumulator: (nullable): the accumulator for this signal; may be %NULL.
+ * @accumulator: (nullable) (scope forever): the accumulator for this signal; may be %NULL.
  * @accu_data: (nullable) (closure accumulator): user data for the @accumulator.
  * @c_marshaller: (nullable): the function to translate arrays of parameter
  *  values to signal emissions into C language callback invocations or %NULL.
@@ -2004,7 +2004,7 @@ g_signal_override_class_closure (guint     signal_id,
  * @signal_name: the name for the signal
  * @instance_type: the instance type on which to override the class handler
  *  for the signal.
- * @class_handler: the handler.
+ * @class_handler: (scope forever): the handler.
  *
  * Overrides the class closure (i.e. the default handler) for the
  * given signal for emissions on instances of @instance_type with