From a355c02a047795852e2bc673e1a48af9e43b2037 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Mon, 10 Apr 2017 09:38:52 +0200 Subject: gir: Update annotations from GLib git master --- gir/gio-2.0.c | 77 ++++++++++++++++++++++++++++++++++++++---------- gir/glib-2.0.c | 2 +- gir/gmodule-2.0.c | 16 ---------- gir/gobject-2.0.c | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 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 @@ -41208,6 +41242,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 @@ -25,22 +25,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 @@ -2243,6 +2243,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 @@ -2310,6 +2325,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 @@ -2859,6 +2890,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 @@ -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. */ @@ -3272,6 +3341,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 -- cgit v1.2.1