Update glib annotations from git master

3 files changed, 143 insertions, 42 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index c1651046..93e376bb 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -2968,6 +2968,23 @@
 
 
 /**
+ * GTask:completed:
+ *
+ * Whether the task has completed, meaning its callback (if set) has been
+ * invoked. This can only happen after g_task_return_pointer(),
+ * g_task_return_error() or one of the other return functions have been called
+ * on the task.
+ *
+ * This property is guaranteed to change from %FALSE to %TRUE exactly once.
+ *
+ * The #GObject::notify signal for this change is emitted in the same main
+ * context as the task’s callback, immediately after that callback is invoked.
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * GTaskThreadFunc:
  * @task: the #GTask
  * @source_object: (type GObject): @task's source object
@@ -5489,9 +5506,15 @@
  * the operation, producing a GAsyncResult which is then passed to the
  * function's matching _finish() operation.
  *
- * Some #GFile operations do not have synchronous analogs, as they may
- * take a very long time to finish, and blocking may leave an application
- * unusable. Notable cases include:
+ * It is highly recommended to use asynchronous calls when running within a
+ * shared main loop, such as in the main thread of an application. This avoids
+ * I/O operations blocking other sources on the main loop from being dispatched.
+ * Synchronous I/O operations should be performed from worker threads. See the
+ * [introduction to asynchronous programming section][async-programming] for
+ * more.
+ *
+ * Some #GFile operations almost always take a noticeable amount of time, and
+ * so do not have synchronous analogs. Notable cases include:
  * - g_file_mount_mountable() to mount a mountable file.
  * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
  * - g_file_eject_mountable_with_operation() to eject a mountable file.
@@ -30234,14 +30257,6 @@
 
 
 /**
- * g_resource_new_from_table:
- * @table: (transfer full): a GvdbTable
- *
- * Returns: (transfer full): a new #GResource for @table
- */
-
-
-/**
  * g_resource_open_stream:
  * @resource: A #GResource
  * @path: A pathname inside the resource
@@ -35989,6 +36004,19 @@
 
 
 /**
+ * g_task_get_completed:
+ * @task: a #GTask.
+ *
+ * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after
+ * the task’s callback is invoked, and will return %FALSE if called from inside
+ * the callback.
+ *
+ * Returns: %TRUE if the task has completed, %FALSE otherwise.
+ * Since: 2.44
+ */
+
+
+/**
  * g_task_get_context:
  * @task: a #GTask
  *
@@ -36361,6 +36389,7 @@
  * Normally this is used with tasks created with a %NULL
  * `callback`, but note that even if the task does
  * have a callback, it will not be invoked when @task_func returns.
+ * #GTask:completed will be set to %TRUE just before this function returns.
  *
  * Since: 2.36
  */
@@ -38696,14 +38725,33 @@
 
 
 /**
+ * g_unix_mount_monitor_get:
+ *
+ * Gets the #GUnixMountMonitor for the current thread-default main
+ * context.
+ *
+ * The mount monitor can be used to monitor for changes to the list of
+ * mounted filesystems as well as the list of mount points (ie: fstab
+ * entries).
+ *
+ * You must only call g_object_unref() on the return value from under
+ * the same main context as you called this function.
+ *
+ * Returns: (transfer full): the #GUnixMountMonitor.
+ * Since: 2.44
+ */
+
+
+/**
  * g_unix_mount_monitor_new:
  *
- * Gets a new #GUnixMountMonitor. The default rate limit for which the
- * monitor will report consecutive changes for the mount and mount
- * point entry files is the default for a #GFileMonitor. Use
- * g_unix_mount_monitor_set_rate_limit() to change this.
+ * Deprecated alias for g_unix_mount_monitor_get().
+ *
+ * This function was never a true constructor, which is why it was
+ * renamed.
  *
  * Returns: a #GUnixMountMonitor.
+ * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead.
  */
 
 
@@ -38713,10 +38761,16 @@
  * @limit_msec: a integer with the limit in milliseconds to
  *     poll for changes.
  *
- * Sets the rate limit to which the @mount_monitor will report
- * consecutive change events to the mount and mount point entry files.
+ * This function does nothing.
+ *
+ * Before 2.44, this was a partially-effective way of controlling the
+ * rate at which events would be reported under some uncommon
+ * circumstances.  Since @mount_monitor is a singleton, it also meant
+ * that calling this function would have side effects for other users of
+ * the monitor.
  *
  * Since: 2.18
+ * Deprecated: 2.44: This function does nothing.  Don't call it.
  */
 
 
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 08625f2b..ef98e45c 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -5636,7 +5636,8 @@
  * functions in GLib and GTK+ do not use the #GError facility.
  *
  * Functions that can fail take a return location for a #GError as their
- * last argument. For example:
+ * last argument. On error, a new #GError instance will be allocated and
+ * returned to the caller via this argument. For example:
  * |[<!-- language="C" -->
  * gboolean g_file_get_contents (const gchar  *filename,
  *                               gchar       **contents,
@@ -5745,7 +5746,8 @@
  * ]|
  *
  * If the sub-function does not indicate errors other than by
- * reporting a #GError, you need to create a temporary #GError
+ * reporting a #GError (or if its return value does not reliably indicate
+ * errors) you need to create a temporary #GError
  * since the passed-in one may be %NULL. g_propagate_error() is
  * intended for use in this case.
  * |[<!-- language="C" -->
@@ -14937,7 +14939,9 @@
  * @mem: (allow-none): the memory to free
  *
  * Frees the memory pointed to by @mem.
- * If @mem is %NULL it simply returns.
+ *
+ * If @mem is %NULL it simply returns, so there is no need to check @mem
+ * against %NULL before calling this function.
  */
 
 
@@ -15632,6 +15636,10 @@
  * Retrieves every key inside @hash_table. The returned data is valid
  * until changes to the hash release those keys.
  *
+ * This iterates over every entry in the hash table to build its return value.
+ * To iterate over the entries in a #GHashTable more efficiently, use a
+ * #GHashTableIter.
+ *
  * Returns: a #GList containing all the keys inside the hash
  *     table. The content of the list is owned by the hash table and
  *     should not be modified or freed. Use g_list_free() when done
@@ -15654,6 +15662,10 @@
  * Note: in the common case of a string-keyed #GHashTable, the return
  * value of this function can be conveniently cast to (const gchar **).
  *
+ * This iterates over every entry in the hash table to build its return value.
+ * To iterate over the entries in a #GHashTable more efficiently, use a
+ * #GHashTableIter.
+ *
  * You should always free the return result with g_free().  In the
  * above-mentioned case of a string-keyed hash table, it may be
  * appropriate to use g_strfreev() if you call g_hash_table_steal_all()
@@ -15672,6 +15684,10 @@
  * Retrieves every value inside @hash_table. The returned data
  * is valid until @hash_table is modified.
  *
+ * This iterates over every entry in the hash table to build its return value.
+ * To iterate over the entries in a #GHashTable more efficiently, use a
+ * #GHashTableIter.
+ *
  * Returns: a #GList containing all the values inside the hash
  *     table. The content of the list is owned by the hash table and
  *     should not be modified or freed. Use g_list_free() when done
@@ -16576,8 +16592,10 @@
  * sources and will not be called again.
  *
  * This internally creates a main loop source using g_idle_source_new()
- * and attaches it to the main loop context using g_source_attach().
- * You can do these steps manually if you need greater control.
+ * and attaches it to the global #GMainContext using g_source_attach(), so
+ * the callback will be invoked in whichever thread is running that main
+ * context. You can do these steps manually if you need greater control or to
+ * use a custom main context.
  *
  * Returns: the ID (greater than 0) of the event source.
  */
@@ -16596,8 +16614,10 @@
  * removed from the list of event sources and will not be called again.
  *
  * This internally creates a main loop source using g_idle_source_new()
- * and attaches it to the main loop context using g_source_attach().
- * You can do these steps manually if you need greater control.
+ * and attaches it to the global #GMainContext using g_source_attach(), so
+ * the callback will be invoked in whichever thread is running that main
+ * context. You can do these steps manually if you need greater control or to
+ * use a custom main context.
  *
  * Returns: the ID (greater than 0) of the event source.
  */
@@ -18408,7 +18428,10 @@
  * g_list_free_1:
  * @list: a #GList element
  *
- * Frees one #GList element.
+ * Frees one #GList element, but does not update links from the next and
+ * previous elements in the list, so you should not call this function on an
+ * element that is currently part of a list.
+ *
  * It is usually used after g_list_remove_link().
  */
 
@@ -18554,6 +18577,10 @@
  *
  * Gets the element at the given position in a #GList.
  *
+ * This iterates over the list until it reaches the @n-th position. If you
+ * intend to iterate over every element, it is better to use a for-loop as
+ * described in the #GList introduction.
+ *
  * Returns: the element, or %NULL if the position is off
  *     the end of the #GList
  */
@@ -18566,6 +18593,10 @@
  *
  * Gets the data of the element at the given position.
  *
+ * This iterates over the list until it reaches the @n-th position. If you
+ * intend to iterate over every element, it is better to use a for-loop as
+ * described in the #GList introduction.
+ *
  * Returns: the element's data, or %NULL if the position
  *     is off the end of the #GList
  */
@@ -22009,7 +22040,7 @@
  * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
  * is not an absolute path it returns %NULL.
  *
- * Returns: a pointer into @file_name after the root component
+ * Returns: (nullable): a pointer into @file_name after the root component
  */
 
 
@@ -27894,7 +27925,7 @@
  * it's %FALSE, the caller gains ownership of the buffer and must
  * free it after use with g_free().
  *
- * Returns: the character data of @string
+ * Returns: (nullable): the character data of @string
  *          (i.e. %NULL if @free_segment is %TRUE)
  */
 
@@ -30346,8 +30377,10 @@
  * optimizations and more efficient system power usage.
  *
  * This internally creates a main loop source using g_timeout_source_new()
- * and attaches it to the main loop context using g_source_attach(). You can
- * do these steps manually if you need greater control.
+ * and attaches it to the global #GMainContext using g_source_attach(), so
+ * the callback will be invoked in whichever thread is running that main
+ * context. You can do these steps manually if you need greater control or to
+ * use a custom main context.
  *
  * The interval given is in terms of monotonic time, not wall clock
  * time.  See g_get_monotonic_time().
@@ -30380,8 +30413,10 @@
  * (it does not try to 'catch up' time lost in delays).
  *
  * This internally creates a main loop source using g_timeout_source_new()
- * and attaches it to the main loop context using g_source_attach(). You can
- * do these steps manually if you need greater control.
+ * and attaches it to the global #GMainContext using g_source_attach(), so
+ * the callback will be invoked in whichever thread is running that main
+ * context. You can do these steps manually if you need greater control or to
+ * use a custom main context.
  *
  * The interval given in terms of monotonic time, not wall clock time.
  * See g_get_monotonic_time().
@@ -30948,7 +30983,9 @@
  *
  * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
  * on failure. Contrast with g_realloc(), which aborts the program
- * on failure. If @mem is %NULL, behaves the same as g_try_malloc().
+ * on failure.
+ *
+ * If @mem is %NULL, behaves the same as g_try_malloc().
  *
  * Returns: the allocated memory, or %NULL.
  */
@@ -33069,11 +33106,11 @@
  * Similar to g_variant_get_string() except that instead of returning
  * a constant string, the string is duplicated.
  *
- * The string will always be utf8 encoded.
+ * The string will always be UTF-8 encoded.
  *
  * The return value must be freed using g_free().
  *
- * Returns: (transfer full): a newly allocated string, utf8 encoded
+ * Returns: (transfer full): a newly allocated string, UTF-8 encoded
  * Since: 2.24
  */
 
@@ -33512,7 +33549,7 @@
  * type.  This includes the types %G_VARIANT_TYPE_STRING,
  * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
  *
- * The string will always be utf8 encoded.
+ * The string will always be UTF-8 encoded.
  *
  * If @length is non-%NULL then the length of the string (in bytes) is
  * returned there.  For trusted values, this information is already
@@ -33523,7 +33560,7 @@
  *
  * The return value remains valid as long as @value exists.
  *
- * Returns: (transfer none): the constant string, utf8 encoded
+ * Returns: (transfer none): the constant string, UTF-8 encoded
  * Since: 2.24
  */
 
@@ -34206,7 +34243,7 @@
  *
  * Creates an array-of-bytes #GVariant with the contents of @string.
  * This function is just like g_variant_new_string() except that the
- * string need not be valid utf8.
+ * string need not be valid UTF-8.
  *
  * The nul terminator character at the end of the string is stored in
  * the array.
@@ -34546,11 +34583,11 @@
 
 /**
  * g_variant_new_string:
- * @string: a normal utf8 nul-terminated string
+ * @string: a normal UTF-8 nul-terminated string
  *
  * Creates a string #GVariant with the contents of @string.
  *
- * @string must be valid utf8.
+ * @string must be valid UTF-8.
  *
  * Returns: (transfer none): a floating reference to a new string #GVariant instance
  * Since: 2.24
@@ -34574,11 +34611,11 @@
 
 /**
  * g_variant_new_take_string: (skip)
- * @string: a normal utf8 nul-terminated string
+ * @string: a normal UTF-8 nul-terminated string
  *
  * Creates a string #GVariant with the contents of @string.
  *
- * @string must be valid utf8.
+ * @string must be valid UTF-8.
  *
  * This function consumes @string.  g_free() will be called on @string
  * when it is no longer required.
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index efe8981a..440d0c2d 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -3310,6 +3310,11 @@
  *
  * Decreases the reference count of @object. When its reference count
  * drops to 0, the object is finalized (i.e. its memory is freed).
+ *
+ * If the pointer to the #GObject may be reused in future (for example, if it is
+ * an instance variable of another object), it is recommended to clear the
+ * pointer to %NULL rather than retain a dangling pointer to a potentially
+ * invalid #GObject instance. Use g_clear_object() for this.
  */
 
 
@@ -3368,7 +3373,10 @@
  * @flags: flags for the property specified
  *
  * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
- * property.
+ * property. In many cases, it may be more appropriate to use an enum with
+ * g_param_spec_enum(), both to improve code clarity by using explicitly named
+ * values, and to allow for more values to be added in future without breaking
+ * API.
  *
  * See g_param_spec_internal() for details on property names.
  *
@@ -3716,6 +3724,8 @@
  * @flags: flags for the property specified
  *
  * Creates a new #GParamSpecPointer instance specifying a pointer property.
+ * Where possible, it is better to use g_param_spec_object() or
+ * g_param_spec_boxed() to expose memory management information.
  *
  * See g_param_spec_internal() for details on property names.
  *