gir: Update annotations from GLib git master

4 files changed, 148 insertions, 34 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 78528551..8ea70cb6 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -13957,6 +13957,9 @@
  * initial construction. If the object also implements #GInitable you can
  * optionally call g_initable_init() instead.
  *
+ * This method is intended for language bindings. If writing in C,
+ * g_async_initable_new_async() should typically be used instead.
+ *
  * When the initialization is finished, @callback will be called. You can
  * then call g_async_initable_init_finish() to get the result of the
  * initialization.
@@ -13974,11 +13977,11 @@
  * have undefined behaviour. They will often fail with g_critical() or
  * g_warning(), but this must not be relied on.
  *
- * Implementations of this method must be idempotent: i.e. multiple calls
- * to this function with the same argument should return the same results.
- * Only the first call initializes the object; further calls return the result
- * of the first call. This is so that it's safe to implement the singleton
- * pattern in the GObject constructor function.
+ * Callers should not assume that a class which implements #GAsyncInitable can
+ * be initialized multiple times; for more information, see g_initable_init().
+ * If a class explicitly supports being initialized multiple times,
+ * implementation requires yielding all subsequent calls to init_async() on the
+ * results of the first call.
  *
  * For classes that also support the #GInitable interface, the default
  * implementation of this method will run the g_initable_init() function
@@ -14088,6 +14091,8 @@
  * for any errors.
  *
  * Since: 2.22
+ * Deprecated: 2.54: Use g_object_new_with_properties() and
+ * g_async_initable_init_async() instead. See #GParameter for more information.
  */
 
 
@@ -26787,6 +26792,9 @@
  *
  * Initializes the object implementing the interface.
  *
+ * This method is intended for language bindings. If writing in C,
+ * g_initable_new() should typically be used instead.
+ *
  * The object must be initialized before any real use after initial
  * construction, either with this function or g_async_initable_init_async().
  *
@@ -26802,11 +26810,24 @@
  * g_object_unref() are considered to be invalid, and have undefined
  * behaviour. See the [introduction][ginitable] for more details.
  *
- * Implementations of this method must be idempotent, i.e. multiple calls
- * to this function with the same argument should return the same results.
- * Only the first call initializes the object, further calls return the result
- * of the first call. This is so that it's safe to implement the singleton
- * pattern in the GObject constructor function.
+ * Callers should not assume that a class which implements #GInitable can be
+ * initialized multiple times, unless the class explicitly documents itself as
+ * supporting this. Generally, a class’ implementation of init() can assume
+ * (and assert) that it will only be called once. Previously, this documentation
+ * recommended all #GInitable implementations should be idempotent; that
+ * recommendation was relaxed in GLib 2.54.
+ *
+ * If a class explicitly supports being initialized multiple times, it is
+ * recommended that the method is idempotent: multiple calls with the same
+ * arguments should return the same results. Only the first call initializes
+ * the object; further calls return the result of the first call.
+ *
+ * One reason why a class might need to support idempotent initialization is if
+ * it is designed to be used via the singleton pattern, with a
+ * #GObjectClass.constructor that sometimes returns an existing instance.
+ * In this pattern, a caller would expect to be able to call g_initable_init()
+ * on the result of g_object_new(), regardless of whether it is in fact a new
+ * instance.
  *
  * Returns: %TRUE if successful. If an error has occurred, this function will
  *     return %FALSE and set @error appropriately if present.
@@ -26871,6 +26892,8 @@
  * Returns: (type GObject.Object) (transfer full): a newly allocated
  *      #GObject, or %NULL on error
  * Since: 2.22
+ * Deprecated: 2.54: Use g_object_new_with_properties() and
+ * g_initable_init() instead. See #GParameter for more information.
  */
 
 
@@ -40986,8 +41009,8 @@
 
 
 /**
- * g_unix_mount_at: (skip)
- * @mount_path: path for a possible unix mount.
+ * g_unix_mount_at:
+ * @mount_path: (type filename): path for a possible unix mount.
  * @time_read: (out) (optional): guint64 to contain a timestamp.
  *
  * Gets a #GUnixMountEntry for a given mount path. If @time_read
@@ -41011,8 +41034,19 @@
 
 
 /**
- * g_unix_mount_for: (skip)
- * @file_path: file path on some unix mount.
+ * g_unix_mount_copy:
+ * @mount_entry: a #GUnixMountEntry.
+ *
+ * Makes a copy of @mount_entry.
+ *
+ * Returns: (transfer full): a new #GUnixMountEntry
+ * Since: 2.54
+ */
+
+
+/**
+ * g_unix_mount_for:
+ * @file_path: (type filename): file path on some unix mount.
  * @time_read: (out) (optional): guint64 to contain a timestamp.
  *
  * Gets a #GUnixMountEntry for a given file path. If @time_read
@@ -41209,6 +41243,17 @@
 
 
 /**
+ * g_unix_mount_point_copy:
+ * @mount_point: a #GUnixMountPoint.
+ *
+ * Makes a copy of @mount_point.
+ *
+ * Returns: (transfer full): a new #GUnixMountPoint
+ * Since: 2.54
+ */
+
+
+/**
  * g_unix_mount_point_free:
  * @mount_point: unix mount point to free.
  *
@@ -41353,7 +41398,7 @@
 
 
 /**
- * g_unix_mount_points_get: (skip)
+ * g_unix_mount_points_get:
  * @time_read: (out) (optional): guint64 to contain a timestamp.
  *
  * Gets a #GList of #GUnixMountPoint containing the unix mount points.
@@ -41377,7 +41422,7 @@
 
 
 /**
- * g_unix_mounts_get: (skip)
+ * g_unix_mounts_get:
  * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL
  *
  * Gets a #GList of #GUnixMountEntry containing the unix mounts.
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index bd277b80..a5e8aa9d 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -32864,7 +32864,7 @@
  * Create a #GSource that will be dispatched upon delivery of the UNIX
  * signal @signum.  In GLib versions before 2.36, only `SIGHUP`, `SIGINT`,
  * `SIGTERM` can be monitored.  In GLib 2.36, `SIGUSR1` and `SIGUSR2`
- * were added.
+ * were added. In GLib 2.54, `SIGWINCH` was added.
  *
  * Note that unlike the UNIX default, all sources which have created a
  * watch will be dispatched, regardless of which underlying thread
diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c
index a57ce315..e8012cd3 100644
--- a/gir/gmodule-2.0.c
+++ b/gir/gmodule-2.0.c
@@ -26,22 +26,6 @@
 
 
 /**
- * GModuleFlags:
- * @G_MODULE_BIND_LAZY: specifies that symbols are only resolved when
- *     needed. The default action is to bind all symbols when the module
- *     is loaded.
- * @G_MODULE_BIND_LOCAL: specifies that symbols in the module should
- *     not be added to the global name space. The default action on most
- *     platforms is to place symbols in the module in the global name space,
- *     which may cause conflicts with existing symbols.
- * @G_MODULE_BIND_MASK: mask for all flags.
- *
- * Flags passed to g_module_open().
- * Note that these flags are not supported on all platforms.
- */
-
-
-/**
  * GModuleUnload:
  * @module: the #GModule about to be unloaded
  *
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index d16d28f4..64534844 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -2244,6 +2244,21 @@
 
 
 /**
+ * g_enum_to_string:
+ * @g_enum_type: the type identifier of a #GEnumClass type
+ * @value: the value
+ *
+ * Pretty-prints @value in the form of the enum’s name.
+ *
+ * This is intended to be used for debugging purposes. The format of the output
+ * may change in the future.
+ *
+ * Returns: (transfer full): a newly-allocated text string
+ * Since: 2.54
+ */
+
+
+/**
  * g_flags_complete_type_info:
  * @g_flags_type: the type identifier of the type being completed
  * @info: (out callee-allocates): the #GTypeInfo struct to be filled in
@@ -2311,6 +2326,22 @@
 
 
 /**
+ * g_flags_to_string:
+ * @flags_type: the type identifier of a #GFlagsClass type
+ * @value: the value
+ *
+ * Pretty-prints @value in the form of the flag names separated by ` | ` and
+ * sorted. Any extra bits will be shown at the end as a hexadecimal number.
+ *
+ * This is intended to be used for debugging purposes. The format of the output
+ * may change in the future.
+ *
+ * Returns: (transfer full): a newly-allocated text string
+ * Since: 2.54
+ */
+
+
+/**
  * g_object_add_toggle_ref: (skip)
  * @object: a #GObject
  * @notify: a function to call when this reference is the
@@ -2860,6 +2891,22 @@
 
 
 /**
+ * g_object_getv:
+ * @object: a #GObject
+ * @n_properties: the number of properties
+ * @names: (array length=n_properties): the names of each property to get
+ * @values: (array length=n_properties): the values of each property to get
+ *
+ * Gets @n_properties properties for an @object.
+ * Obtained properties will be set to @values. All properties must be valid.
+ * Warnings will be emitted and undefined behaviour may result if invalid
+ * properties are passed in.
+ *
+ * Since: 2.54
+ */
+
+
+/**
  * g_object_interface_find_property:
  * @g_iface: (type GObject.TypeInterface): any interface vtable for the
  *  interface, or the default vtable for the interface
@@ -2969,7 +3016,27 @@
 
 
 /**
- * g_object_newv: (rename-to g_object_new)
+ * g_object_new_with_properties: (rename-to g_object_new)
+ * @object_type: the object type to instantiate
+ * @n_properties: the number of properties
+ * @names: (array length=n_properties): the names of each property to be set
+ * @values: (array length=n_properties): the values of each property to be set
+ *
+ * Creates a new instance of a #GObject subtype and sets its properties using
+ * the provided arrays. Both arrays must have exactly @n_properties elements,
+ * and the names and values correspond by index.
+ *
+ * Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY)
+ * which are not explicitly specified are set to their default values.
+ *
+ * Returns: (type GObject.Object) (transfer full): a new instance of
+ * @object_type
+ * Since: 2.54
+ */
+
+
+/**
+ * g_object_newv:
  * @object_type: the type id of the #GObject subtype to instantiate
  * @n_parameters: the length of the @parameters array
  * @parameters: (array length=n_parameters): an array of #GParameter
@@ -2981,6 +3048,8 @@
  *
  * Returns: (type GObject.Object) (transfer full): a new instance of
  * @object_type
+ * Deprecated: 2.54: Use g_object_new_with_properties() instead.
+ * deprecated. See #GParameter for more information.
  */
 
 
@@ -3273,6 +3342,22 @@
 
 
 /**
+ * g_object_setv: (skip)
+ * @object: a #GObject
+ * @n_properties: the number of properties
+ * @names: (array length=n_properties): the names of each property to be set
+ * @values: (array length=n_properties): the values of each property to be set
+ *
+ * Sets @n_properties properties for an @object.
+ * Properties to be set will be taken from @values. All properties must be
+ * valid. Warnings will be emitted and undefined behaviour may result if invalid
+ * properties are passed in.
+ *
+ * Since: 2.54
+ */
+
+
+/**
  * g_object_steal_data:
  * @object: #GObject containing the associations
  * @key: name of the key