Merge branch '3037-doc-build-cleanups' into 'main'

build: Rename -Dgtk_doc option to -Ddocumentation and fix some g-ir-scanner warnings

See merge request GNOME/glib!3736

.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

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`
+`-Ddocumentation=false` and `-Ddocumentation=true`
-: By default, GLib will detect whether the gtk-doc package is installed.
+: By default, GLib will not build documentation for the library and tools. This
-  If it is, then it will use it to extract and build the documentation
+  option can be used to enable building 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.
 
 `-Dman=false` and `-Dman=true`
 : By default, GLib will detect whether `xsltproc` and the necessary DocBook

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)
 

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)

gio/gdbusmessage.c

@@ -3618,7 +3618,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
@@ -3631,9 +3631,9 @@ _sort_keys_func (gconstpointer a,
  * Body: ()
  * UNIX File Descriptors:
  *   (none)
- * ]|
+ * ```
  * or
- * |[
+ * ```
  * Type:    method-return
  * Flags:   no-reply-expected
  * Version: 0
@@ -3646,9 +3646,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
  */

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_acquired_handler: (nullable) (scope notified): handler to invoke when
- * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL
+ *   @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
+ * @bus_acquired_handler: (nullable) (scope notified): handler to invoke when
- * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL
+ *   connected to the bus of type @bus_type 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
  *

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_appeared_handler: (nullable) (scope notified): Handler to invoke when
- * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL.
+ *   @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_appeared_handler: (nullable) (scope notified): Handler to invoke when
- * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL.
+ *   @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.
  *

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

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

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.

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

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

gio/gtlspassword.c

@@ -251,7 +251,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

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.

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.

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

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

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
 

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

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.

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_init: (scope forever): function initializing fields of the private error data
- * @error_type_copy: function copying fields of the private error data
+ * @error_type_copy: (scope forever): function copying fields of the private error data
- * @error_type_clear: function freeing 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_init: (scope forever): function initializing fields of the private error data
- * @error_type_copy: function copying fields of the private error data
+ * @error_type_copy: (scope forever): function copying fields of the private error data
- * @error_type_clear: function freeing 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

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
@@ -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

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

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 

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

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,
+ * @copy_func: (scope call): the function which is called to copy the data
- *   or %NULL to use the original 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

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

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

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
  *

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

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

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.

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.

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);
 

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_copy: (scope forever): Boxed structure copy function.
- * @boxed_free: Boxed structure free 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.

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

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'),

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',