[gobject-introspection] Update glib annotations

[Christoph Reiter <creiter src gnome org>]

commit 65be48bdefe8c48a92cc54a2c525f4acccc9b5e8
Author: Christoph Reiter <reiter christoph gmail com>
Date:   Mon Dec 31 13:28:00 2018 +0100

    Update glib annotations

 gir/gio-2.0.c     | 267 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 gir/glib-2.0.c    | 125 ++++++++++++++++++-------
 gir/gobject-2.0.c |   8 +-
 3 files changed, 356 insertions(+), 44 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 87a9db7d..f4fa552d 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -1645,6 +1645,17 @@
  */
 
 
+/**
+ * GDtlsConnection:advertised-protocols:
+ *
+ * The list of application-layer protocols that the connection
+ * advertises that it is willing to speak. See
+ * g_dtls_connection_set_advertised_protocols().
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * GDtlsConnection:base-socket:
  *
@@ -1687,6 +1698,16 @@
  */
 
 
+/**
+ * GDtlsConnection:negotiated-protocol:
+ *
+ * The application-layer protocol negotiated during the TLS
+ * handshake. See g_dtls_connection_get_negotiated_protocol().
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * GDtlsConnection:peer-certificate:
  *
@@ -3692,6 +3713,17 @@
  */
 
 
+/**
+ * GTlsConnection:advertised-protocols:
+ *
+ * The list of application-layer protocols that the connection
+ * advertises that it is willing to speak. See
+ * g_tls_connection_set_advertised_protocols().
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * GTlsConnection:base-io-stream:
  *
@@ -3737,6 +3769,16 @@
  */
 
 
+/**
+ * GTlsConnection:negotiated-protocol:
+ *
+ * The application-layer protocol negotiated during the TLS
+ * handshake. See g_tls_connection_get_negotiated_protocol().
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * GTlsConnection:peer-certificate:
  *
@@ -5162,13 +5204,13 @@
  *
  * A content type is a platform specific string that defines the type
  * of a file. On UNIX it is a
- * [mime type](http://www.wikipedia.org/wiki/Internet_media_type)
- * like "text/plain" or "image/png".
- * On Win32 it is an extension string like ".doc", ".txt" or a perceived
- * string like "audio". Such strings can be looked up in the registry at
- * HKEY_CLASSES_ROOT.
- * On OSX it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier)
- * such as "com.apple.application".
+ * [MIME type](http://www.wikipedia.org/wiki/Internet_media_type)
+ * like `text/plain` or `image/png`.
+ * On Win32 it is an extension string like `.doc`, `.txt` or a perceived
+ * string like `audio`. Such strings can be looked up in the registry at
+ * `HKEY_CLASSES_ROOT`.
+ * On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier)
+ * such as `com.apple.application`.
  */
 
 
@@ -7259,6 +7301,23 @@
  */
 
 
+/**
+ * SECTION:gproxyaddressenumerator
+ * @short_description: Proxy wrapper enumerator for socket addresses
+ * @include: gio/gio.h
+ *
+ * #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which
+ * takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator
+ * and wraps them in #GProxyAddress instances, using the given
+ * #GProxyAddressEnumerator:proxy-resolver.
+ *
+ * This enumerator will be returned (for example, by
+ * g_socket_connectable_enumerate()) as appropriate when a proxy is configured;
+ * there should be no need to manually wrap a #GSocketAddressEnumerator instance
+ * with one.
+ */
+
+
 /**
  * SECTION:gproxyresolver
  * @short_description: Asynchronous and cancellable network proxy resolver
@@ -8235,6 +8294,28 @@
  */
 
 
+/**
+ * SECTION:gsocketaddressenumerator
+ * @short_description: Enumerator for socket addresses
+ * @include: gio/gio.h
+ *
+ * #GSocketAddressEnumerator is an enumerator type for #GSocketAddress
+ * instances. It is returned by enumeration functions such as
+ * g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator
+ * to list all the #GSocketAddresses which could be used to connect to that
+ * #GSocketConnectable.
+ *
+ * Enumeration is typically a blocking operation, so the asynchronous methods
+ * g_socket_address_enumerator_next_async() and
+ * g_socket_address_enumerator_next_finish() should be used where possible.
+ *
+ * Each #GSocketAddressEnumerator can only be enumerated once. Once
+ * g_socket_address_enumerator_next() has returned %NULL (and no error), further
+ * enumeration with that #GSocketAddressEnumerator is not possible, and it can
+ * be unreffed.
+ */
+
+
 /**
  * SECTION:gsocketclient
  * @short_description: Helper for connecting to a network service
@@ -13487,6 +13568,19 @@
  */
 
 
+/**
+ * g_content_type_get_mime_dirs:
+ *
+ * Get the list of directories which MIME data is loaded from. See
+ * g_content_type_set_mime_dirs() for details.
+ *
+ * Returns: (transfer none) (array zero-terminated=1): %NULL-terminated list of
+ *    directories to load MIME data from, including any `mime/` subdirectory,
+ *    and with the first directory to try listed first
+ * Since: 2.60
+ */
+
+
 /**
  * g_content_type_get_mime_type:
  * @type: a content type string
@@ -13590,12 +13684,46 @@
  */
 
 
+/**
+ * g_content_type_set_mime_dirs:
+ * @dirs: (array zero-terminated=1) (nullable): %NULL-terminated list of
+ *    directories to load MIME data from, including any `mime/` subdirectory,
+ *    and with the first directory to try listed first
+ *
+ * Set the list of directories used by GIO to load the MIME database.
+ * If @dirs is %NULL, the directories used are the default:
+ *
+ *  - the `mime` subdirectory of the directory in `$XDG_DATA_HOME`
+ *  - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS`
+ *
+ * This function is intended to be used when writing tests that depend on
+ * information stored in the MIME database, in order to control the data.
+ *
+ * Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they
+ * depend on the system’s MIME database, you should call this function
+ * with @dirs set to %NULL before calling g_test_init(), for instance:
+ *
+ * |[<!-- language="C" -->
+ *   // Load MIME data from the system
+ *   g_content_type_set_mime_dirs (NULL);
+ *   // Isolate the environment
+ *   g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL);
+ *
+ *   …
+ *
+ *   return g_test_run ();
+ * ]|
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * g_content_types_get_registered:
  *
  * Gets a list of strings containing all the registered content types
  * known to the system. The list and its data should be freed using
- * g_list_free_full (list, g_free).
+ * `g_list_free_full (list, g_free)`.
  *
  * Returns: (element-type utf8) (transfer full): list of the registered
  *     content types
@@ -15413,6 +15541,17 @@
  */
 
 
+/**
+ * g_dbus_connection_get_flags:
+ * @connection: a #GDBusConnection
+ *
+ * Gets the flags used to construct this connection
+ *
+ * Returns: zero or more flags from the #GDBusConnectionFlags enumeration
+ * Since: 2.60
+ */
+
+
 /**
  * g_dbus_connection_get_guid:
  * @connection: a #GDBusConnection
@@ -20039,6 +20178,23 @@
  */
 
 
+/**
+ * g_dtls_connection_get_negotiated_protocol:
+ * @conn: a #GDtlsConnection
+ *
+ * Gets the name of the application-layer protocol negotiated during
+ * the handshake.
+ *
+ * If the peer did not use the ALPN extension, or did not advertise a
+ * protocol that matched one of @conn's protocols, or the TLS backend
+ * does not support ALPN, then this will be %NULL. See
+ * g_dtls_connection_set_advertised_protocols().
+ *
+ * Returns: (nullable): the negotiated protocol, or %NULL
+ * Since: 2.60
+ */
+
+
 /**
  * g_dtls_connection_get_peer_certificate:
  * @conn: a #GDtlsConnection
@@ -20161,6 +20317,27 @@
  */
 
 
+/**
+ * g_dtls_connection_set_advertised_protocols:
+ * @conn: a #GDtlsConnection
+ * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated
+ *   array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
+ *
+ * Sets the list of application-layer protocols to advertise that the
+ * caller is willing to speak on this connection. The
+ * Application-Layer Protocol Negotiation (ALPN) extension will be
+ * used to negotiate a compatible protocol with the peer; use
+ * g_dtls_connection_get_negotiated_protocol() to find the negotiated
+ * protocol after the handshake.  Specifying %NULL for the the value
+ * of @protocols will disable ALPN negotiation.
+ *
+ * See [IANA TLS ALPN Protocol 
IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
+ * for a list of registered protocol IDs.
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * g_dtls_connection_set_certificate:
  * @conn: a #GDtlsConnection
@@ -36434,6 +36611,9 @@
  *
  * Like g_subprocess_communicate(), but validates the output of the
  * process as UTF-8, and returns it as a regular NUL terminated string.
+ *
+ * On error, @stdout_buf and @stderr_buf will be set to undefined values and
+ * should not be used.
  */
 
 
@@ -37149,6 +37329,9 @@
  * #GMainContext with @task's [priority][io-priority], and sets @source's
  * callback to @callback, with @task as the callback's `user_data`.
  *
+ * It will set the @source’s name to the task’s name (as set with
+ * g_task_set_name()), if one has been set.
+ *
  * This takes a reference on @task until @source is destroyed.
  *
  * Since: 2.36
@@ -37207,6 +37390,17 @@
  */
 
 
+/**
+ * g_task_get_name:
+ * @task: a #GTask
+ *
+ * Gets @task’s name. See g_task_set_name().
+ *
+ * Returns: (nullable) (transfer none): @task’s name, or %NULL
+ * Since: 2.60
+ */
+
+
 /**
  * g_task_get_priority:
  * @task: a #GTask
@@ -37606,6 +37800,25 @@
  */
 
 
+/**
+ * g_task_set_name:
+ * @task: a #GTask
+ * @name: (nullable): a human readable name for the task, or %NULL to unset it
+ *
+ * Sets @task’s name, used in debugging and profiling. The name defaults to
+ * %NULL.
+ *
+ * The task name should describe in a human readable way what the task does.
+ * For example, ‘Open file’ or ‘Connect to network host’. It is used to set the
+ * name of the #GSource used for idle completion of the task.
+ *
+ * This function may only be called before the @task is first used in a thread
+ * other than the one it was constructed in.
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * g_task_set_priority:
  * @task: the #GTask
@@ -38452,6 +38665,23 @@
  */
 
 
+/**
+ * g_tls_connection_get_negotiated_protocol:
+ * @conn: a #GTlsConnection
+ *
+ * Gets the name of the application-layer protocol negotiated during
+ * the handshake.
+ *
+ * If the peer did not use the ALPN extension, or did not advertise a
+ * protocol that matched one of @conn's protocols, or the TLS backend
+ * does not support ALPN, then this will be %NULL. See
+ * g_tls_connection_set_advertised_protocols().
+ *
+ * Returns: (nullable): the negotiated protocol, or %NULL
+ * Since: 2.60
+ */
+
+
 /**
  * g_tls_connection_get_peer_certificate:
  * @conn: a #GTlsConnection
@@ -38590,6 +38820,27 @@
  */
 
 
+/**
+ * g_tls_connection_set_advertised_protocols:
+ * @conn: a #GTlsConnection
+ * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated
+ *   array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
+ *
+ * Sets the list of application-layer protocols to advertise that the
+ * caller is willing to speak on this connection. The
+ * Application-Layer Protocol Negotiation (ALPN) extension will be
+ * used to negotiate a compatible protocol with the peer; use
+ * g_tls_connection_get_negotiated_protocol() to find the negotiated
+ * protocol after the handshake.  Specifying %NULL for the the value
+ * of @protocols will disable ALPN negotiation.
+ *
+ * See [IANA TLS ALPN Protocol 
IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
+ * for a list of registered protocol IDs.
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * g_tls_connection_set_certificate:
  * @conn: a #GTlsConnection
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index c70f2746..aa46726e 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -1514,6 +1514,10 @@
  * simultaneous read-only access (by holding the 'reader' lock via
  * g_rw_lock_reader_lock()).
  *
+ * It is unspecified whether readers or writers have priority in acquiring the
+ * lock when a reader already holds the lock and a writer is queued to acquire
+ * it.
+ *
  * Here is an example for an array with access functions:
  * |[<!-- language="C" -->
  *   GRWLock lock;
@@ -2732,6 +2736,19 @@
  */
 
 
+/**
+ * G_ALIGNOF:
+ * @a: a type-name
+ *
+ * Return the minimum alignment required by the platform ABI for values of the given
+ * type. The address of a variable or struct member of the given type must always be
+ * a multiple of this alignment. For example, most platforms require int variables
+ * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms.
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * G_APPROX_VALUE:
  * @a: a numeric value
@@ -7408,7 +7425,8 @@
  * The "GMarkup" parser is intended to parse a simple markup format
  * that's a subset of XML. This is a small, efficient, easy-to-use
  * parser. It should not be used if you expect to interoperate with
- * other applications generating full-scale XML. However, it's very
+ * other applications generating full-scale XML, and must not be used if you
+ * expect to parse untrusted input. However, it's very
  * useful for application data files, config files, etc. where you
  * know your application will be the only one writing the file.
  * Full-scale XML parsers should be able to parse the subset used by
@@ -8497,7 +8515,8 @@
  * In addition to the traditional g_assert_true(), the test framework provides
  * an extended set of assertions for comparisons: g_assert_cmpfloat(),
  * g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(),
- * g_assert_cmphex(), g_assert_cmpstr(), and g_assert_cmpmem(). The
+ * g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and
+ * g_assert_cmpvariant(). The
  * advantage of these variants over plain g_assert_true() is that the assertion
  * messages can be more elaborate, and include the values of the compared
  * entities.
@@ -10068,7 +10087,7 @@
  * g_assert_cmpfloat:
  * @n1: an floating point number
  * @cmp: The comparison operator to use.
- *     One of ==, !=, <, >, <=, >=.
+ *     One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
  * @n2: another floating point number
  *
  * Debugging macro to compare two floating point numbers.
@@ -10104,7 +10123,7 @@
  * g_assert_cmphex:
  * @n1: an unsigned integer
  * @cmp: The comparison operator to use.
- *     One of ==, !=, <, >, <=, >=.
+ *     One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
  * @n2: another unsigned integer
  *
  * Debugging macro to compare to unsigned integers.
@@ -10120,7 +10139,7 @@
  * g_assert_cmpint:
  * @n1: an integer
  * @cmp: The comparison operator to use.
- *     One of ==, !=, <, >, <=, >=.
+ *     One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
  * @n2: another integer
  *
  * Debugging macro to compare two integers.
@@ -10162,7 +10181,7 @@
  * g_assert_cmpstr:
  * @s1: a string (may be %NULL)
  * @cmp: The comparison operator to use.
- *     One of ==, !=, <, >, <=, >=.
+ *     One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
  * @s2: another string (may be %NULL)
  *
  * Debugging macro to compare two strings. If the comparison fails,
@@ -10187,7 +10206,7 @@
  * g_assert_cmpuint:
  * @n1: an unsigned integer
  * @cmp: The comparison operator to use.
- *     One of ==, !=, <, >, <=, >=.
+ *     One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
  * @n2: another unsigned integer
  *
  * Debugging macro to compare two unsigned integers.
@@ -10201,6 +10220,24 @@
  */
 
 
+/**
+ * g_assert_cmpvariant:
+ * @v1: pointer to a #GVariant
+ * @v2: pointer to another #GVariant
+ *
+ * Debugging macro to compare two #GVariants. If the comparison fails,
+ * an error message is logged and the application is either terminated
+ * or the testcase marked as failed. The variants are compared using
+ * g_variant_equal().
+ *
+ * The effect of `g_assert_cmpvariant (v1, v2)` is the same as
+ * `g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is
+ * that it can produce a message that includes the actual values of @v1 and @v2.
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * g_assert_error:
  * @err: a #GError, possibly %NULL
@@ -10218,7 +10255,7 @@
  *
  * This can only be used to test for a specific error. If you want to
  * test that @err is set, but don't care what it's set to, just use
- * `g_assert (err != NULL)`
+ * `g_assert_nonnull (err)`.
  *
  * Since: 2.20
  */
@@ -11131,6 +11168,9 @@
  * The data will be freed when its reference count drops to
  * zero.
  *
+ * The allocated data is guaranteed to be suitably aligned for any
+ * built-in type.
+ *
  * Returns: (transfer full) (not nullable): a pointer to the allocated memory
  * Since: 2.58
  */
@@ -11148,6 +11188,9 @@
  * The data will be freed when its reference count drops to
  * zero.
  *
+ * The allocated data is guaranteed to be suitably aligned for any
+ * built-in type.
+ *
  * Returns: (transfer full) (not nullable): a pointer to the allocated memory
  * Since: 2.58
  */
@@ -25924,6 +25967,9 @@
  * The data will be freed when its reference count drops to
  * zero.
  *
+ * The allocated data is guaranteed to be suitably aligned for any
+ * built-in type.
+ *
  * Returns: (transfer full) (not nullable): a pointer to the allocated memory
  * Since: 2.58
  */
@@ -25941,6 +25987,9 @@
  * The data will be freed when its reference count drops to
  * zero.
  *
+ * The allocated data is guaranteed to be suitably aligned for any
+ * built-in type.
+ *
  * Returns: (transfer full) (not nullable): a pointer to the allocated memory
  * Since: 2.58
  */
@@ -26946,7 +26995,7 @@
  * that the latest on-disk version is used. Call this only
  * if you just changed the data on disk yourself.
  *
- * Due to threadsafety issues this may cause leaking of strings
+ * Due to thread safety issues this may cause leaking of strings
  * that were previously returned from g_get_user_special_dir()
  * that can't be freed. We ensure to only leak the data for
  * the directories that actually changed value though.
@@ -31556,35 +31605,31 @@
 
 
 /**
- * g_strv_length:
- * @str_array: a %NULL-terminated array of strings
+ * g_strv_equal:
+ * @strv1: a %NULL-terminated array of strings
+ * @strv2: another %NULL-terminated array of strings
  *
- * Returns the length of the given %NULL-terminated
- * string array @str_array. @str_array must not be %NULL.
+ * Checks if @strv1 and @strv2 contain exactly the same elements in exactly the
+ * same order. Elements are compared using g_str_equal(). To match independently
+ * of order, sort the arrays first (using g_qsort_with_data() or similar).
  *
- * Returns: length of @str_array.
- * Since: 2.6
+ * Two empty arrays are considered equal. Neither @strv1 not @strv2 may be
+ * %NULL.
+ *
+ * Returns: %TRUE if @strv1 and @strv2 are equal
+ * Since: 2.60
  */
 
 
 /**
- * g_test_add:
- * @testpath: The test path for a new test case.
- * @Fixture: The type of a fixture data structure.
- * @tdata: Data argument for the test functions.
- * @fsetup: The function to set up the fixture data.
- * @ftest: The actual test function.
- * @fteardown: The function to tear down the fixture data.
- *
- * Hook up a new test case at @testpath, similar to g_test_add_func().
- * A fixture data structure with setup and teardown functions may be provided,
- * similar to g_test_create_case().
+ * g_strv_length:
+ * @str_array: a %NULL-terminated array of strings
  *
- * g_test_add() is implemented as a macro, so that the fsetup(), ftest() and
- * fteardown() callbacks can expect a @Fixture pointer as their first argument
- * in a type safe manner. They otherwise have type #GTestFixtureFunc.
+ * Returns the length of the given %NULL-terminated
+ * string array @str_array. @str_array must not be %NULL.
  *
- * Since: 2.16
+ * Returns: length of @str_array.
+ * Since: 2.6
  */
 
 
@@ -31604,6 +31649,10 @@
  * the test will be skipped by default, and only run if explicitly
  * required via the `-p` command-line option or g_test_trap_subprocess().
  *
+ * No component of @testpath may start with a dot (`.`) if the
+ * %G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
+ * do so even if it isn’t.
+ *
  * Since: 2.16
  */
 
@@ -31636,6 +31685,10 @@
  * the test will be skipped by default, and only run if explicitly
  * required via the `-p` command-line option or g_test_trap_subprocess().
  *
+ * No component of @testpath may start with a dot (`.`) if the
+ * %G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
+ * do so even if it isn’t.
+ *
  * Since: 2.16
  */
 
@@ -31923,9 +31976,7 @@
  *        Changed if any arguments were handled.
  * @argv: Address of the @argv parameter of main().
  *        Any parameters understood by g_test_init() stripped before return.
- * @...: %NULL-terminated list of special options. Currently the only
- *       defined option is `"no_g_set_prgname"`, which
- *       will cause g_test_init() to not call g_set_prgname().
+ * @...: %NULL-terminated list of special options, documented below.
  *
  * Initialize the GLib testing framework, e.g. by seeding the
  * test random number generator, the name for g_get_prgname()
@@ -31959,6 +32010,14 @@
  *
  * - `--debug-log`: Debug test logging output.
  *
+ * Options which can be passed to @... are:
+ *
+ *  - `"no_g_set_prgname"`: Causes g_test_init() to not call g_set_prgname().
+ *  - %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each
+ *    unit test and uses g_set_user_dirs() to set XDG directories to point into
+ *    that temporary directory for the duration of the unit test. See the
+ *    documentation for %G_TEST_OPTION_ISOLATE_DIRS.
+ *
  * Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined,
  * g_test_init() will print an error and exit. This is to prevent no-op tests
  * from being executed, as g_assert() is commonly (erroneously) used in unit
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 079a6248..67539ec5 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -2380,9 +2380,11 @@
  * of bidirectional bindings, otherwise it will be ignored
  *
  * The binding will automatically be removed when either the @source or the
- * @target instances are finalized. To remove the binding without affecting the
- * @source and the @target you can just call g_object_unref() on the returned
- * #GBinding instance.
+ * @target instances are finalized. This will release the reference that is
+ * being held on the #GBinding instance; if you want to hold on to the
+ * #GBinding instance, you will need to hold a reference to it.
+ *
+ * To remove the binding, call g_binding_unbind().
  *
  * A #GObject can have multiple bindings.
  *