Update glib annotations

2 files changed, 56 insertions, 63 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 197a7616..f9df1751 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -3628,19 +3628,6 @@
 
 
 /**
- * GTlsCertificate:pkcs11-uri: (nullable)
- *
- * A URI referencing the PKCS \#11 objects containing an X.509 certificate
- * and optionally a private key.
- *
- * If %NULL the certificate is either not backed by PKCS \#11 or the
- * #GTlsBackend does not support PKCS \#11.
- *
- * Since: 2.64
- */
-
-
-/**
  * GTlsCertificate:private-key:
  *
  * The DER (binary) encoded representation of the certificate's
@@ -3676,15 +3663,6 @@
 
 
 /**
- * GTlsCertificate:private-key-pkcs11-uri: (nullable)
- *
- * A URI referencing a PKCS \#11 object containing a private key.
- *
- * Since: 2.64
- */
-
-
-/**
  * GTlsClientConnection:
  *
  * Abstract base class for the backend-specific client connection
@@ -16389,6 +16367,24 @@
  * signal is unsubscribed from, and may be called after @connection
  * has been destroyed.)
  *
+ * As @callback is potentially invoked in a different thread from where it’s
+ * emitted, it’s possible for this to happen after
+ * g_dbus_connection_signal_unsubscribe() has been called in another thread.
+ * Due to this, @user_data should have a strong reference which is freed with
+ * @user_data_free_func, rather than pointing to data whose lifecycle is tied
+ * to the signal subscription. For example, if a #GObject is used to store the
+ * subscription ID from g_dbus_connection_signal_subscribe(), a strong reference
+ * to that #GObject must be passed to @user_data, and g_object_unref() passed to
+ * @user_data_free_func. You are responsible for breaking the resulting
+ * reference count cycle by explicitly unsubscribing from the signal when
+ * dropping the last external reference to the #GObject. Alternatively, a weak
+ * reference may be used.
+ *
+ * It is guaranteed that if you unsubscribe from a signal using
+ * g_dbus_connection_signal_unsubscribe() from the same thread which made the
+ * corresponding g_dbus_connection_signal_subscribe() call, @callback will not
+ * be invoked after g_dbus_connection_signal_unsubscribe() returns.
+ *
  * The returned subscription identifier is an opaque value which is guaranteed
  * to never be zero.
  *
@@ -23714,10 +23710,6 @@
  * If the flag #G_FILE_COPY_OVERWRITE is specified an already
  * existing @destination file is overwritten.
  *
- * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
- * will be copied as symlinks, otherwise the target of the
- * @source symlink will be copied.
- *
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -29319,7 +29311,7 @@
 /**
  * g_network_monitor_base_add_network:
  * @monitor: the #GNetworkMonitorBase
- * @network: a #GInetAddressMask
+ * @network: (transfer none): a #GInetAddressMask
  *
  * Adds @network to @monitor's list of available networks.
  *
@@ -39093,41 +39085,6 @@
 
 
 /**
- * g_tls_certificate_new_from_pkcs11_uris:
- * @pkcs11_uri: A PKCS \#11 URI
- * @private_key_pkcs11_uri: (nullable): A PKCS \#11 URI
- * @error: #GError for error reporting, or %NULL to ignore.
- *
- * Creates a #GTlsCertificate from a PKCS \#11 URI.
- *
- * An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01`
- *
- * Where the token’s layout is:
- *
- * ```
- * Object 0:
- *   URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private
- *   Type: Private key (RSA-2048)
- *   ID: 01
- *
- * Object 1:
- *   URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert
- *   Type: X.509 Certificate (RSA-2048)
- *   ID: 01
- * ```
- *
- * In this case the certificate and private key would both be detected and used as expected.
- * @pkcs_uri may also just reference an X.509 certificate object and then optionally
- * @private_key_pkcs11_uri allows using a private key exposed under a different URI.
- *
- * Note that the private key is not accessed until usage and may fail or require a PIN later.
- *
- * Returns: (transfer full): the new certificate, or %NULL on error
- * Since: 2.64
- */
-
-
-/**
  * g_tls_certificate_verify:
  * @cert: a #GTlsCertificate
  * @identity: (nullable): the expected peer identity
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 4830ee57..cb671c7a 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -17264,12 +17264,16 @@
 /**
  * g_hash_table_add:
  * @hash_table: a #GHashTable
- * @key: a key to insert
+ * @key: (transfer full): a key to insert
  *
  * This is a convenience function for using a #GHashTable as a set.  It
  * is equivalent to calling g_hash_table_replace() with @key as both the
  * key and the value.
  *
+ * In particular, this means that if @key already exists in the hash table, then
+ * the old copy of @key in the hash table is freed and @key replaces it in the
+ * table.
+ *
  * When a hash table only ever contains keys that have themselves as the
  * corresponding value it is able to be stored more efficiently.  See
  * the discussion in the section description.
@@ -20323,6 +20327,13 @@
  *
  * If list elements contain dynamically-allocated memory, you should
  * either use g_list_free_full() or free them manually first.
+ *
+ * It can be combined with g_steal_pointer() to ensure the list head pointer
+ * is not left dangling:
+ * |[<!-- language="C" -->
+ * GList *list_of_borrowed_things = …;  /<!-- -->* (transfer container) *<!-- -->/
+ * g_list_free (g_steal_pointer (&list_of_borrowed_things));
+ * ]|
  */
 
 
@@ -20356,6 +20367,15 @@
  * @free_func must not modify the list (eg, by removing the freed
  * element from it).
  *
+ * It can be combined with g_steal_pointer() to ensure the list head pointer
+ * is not left dangling ­— this also has the nice property that the head pointer
+ * is cleared before any of the list elements are freed, to prevent double frees
+ * from @free_func:
+ * |[<!-- language="C" -->
+ * GList *list_of_owned_things = …;  /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
+ * g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
+ * ]|
+ *
  * Since: 2.28
  */
 
@@ -28900,6 +28920,13 @@
  * If list elements contain dynamically-allocated memory,
  * you should either use g_slist_free_full() or free them manually
  * first.
+ *
+ * It can be combined with g_steal_pointer() to ensure the list head pointer
+ * is not left dangling:
+ * |[<!-- language="C" -->
+ * GSList *list_of_borrowed_things = …;  /<!-- -->* (transfer container) *<!-- -->/
+ * g_slist_free (g_steal_pointer (&list_of_borrowed_things));
+ * ]|
  */
 
 
@@ -28932,6 +28959,15 @@
  * @free_func must not modify the list (eg, by removing the freed
  * element from it).
  *
+ * It can be combined with g_steal_pointer() to ensure the list head pointer
+ * is not left dangling ­— this also has the nice property that the head pointer
+ * is cleared before any of the list elements are freed, to prevent double frees
+ * from @free_func:
+ * |[<!-- language="C" -->
+ * GSList *list_of_owned_things = …;  /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
+ * g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
+ * ]|
+ *
  * Since: 2.28
  */