[gobject-introspection] gir: Update annotations from GLib git master

[Rico Tzschichholz <ricotz src gnome org>]

commit ea9dd2eb2d0d3898d349d8f7e254b1326fc83a33
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Mon Mar 14 11:40:40 2016 +0100

    gir: Update annotations from GLib git master

 gir/gio-2.0.c     |    2 +-
 gir/glib-2.0.c    |   31 ++++++++++++++-----------------
 gir/gobject-2.0.c |    2 +-
 3 files changed, 16 insertions(+), 19 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 9692f5d..e8d740a 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -4338,7 +4338,7 @@
  * In all cases, the implementing class is responsible for storing the
  * name of the action, the parameter type, the enabled state, the
  * optional state type and the state and emitting the appropriate
- * signals when these change.  The implementor responsible for filtering
+ * signals when these change.  The implementor is responsible for filtering
  * calls to g_action_activate() and g_action_change_state() for type
  * safety and for the state being enabled.
  *
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index c6ad5b8..b423ccf 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -5974,22 +5974,19 @@
  *   g_set_error() will complain if you pile up errors.
  *
  * - By convention, if you return a boolean value indicating success
- *   then %TRUE means success and %FALSE means failure.
- *   <footnote><para>Avoid creating functions which have a boolean
- *   return value and a GError parameter, but where the boolean does
- *   something other than signal whether the GError is set.  Among other
- *   problems, it requires C callers to allocate a temporary error.  Instead,
- *   provide a "gboolean *" out parameter. There are functions in GLib
- *   itself such as g_key_file_has_key() that are deprecated because of this.
- *   </para></footnote>
- *   If %FALSE is
- *   returned, the error must be set to a non-%NULL value.
- *   <footnote><para>One exception to this is that in situations that are
- *   already considered to be undefined behaviour (such as when a
+ *   then %TRUE means success and %FALSE means failure. Avoid creating
+ *   functions which have a boolean return value and a GError parameter,
+ *   but where the boolean does something other than signal whether the
+ *   GError is set.  Among other problems, it requires C callers to allocate
+ *   a temporary error.  Instead, provide a "gboolean *" out parameter.
+ *   There are functions in GLib itself such as g_key_file_has_key() that
+ *   are deprecated because of this. If %FALSE is returned, the error must
+ *   be set to a non-%NULL value.  One exception to this is that in situations
+ *   that are already considered to be undefined behaviour (such as when a
  *   g_return_val_if_fail() check fails), the error need not be set.
  *   Instead of checking separately whether the error is set, callers
  *   should ensure that they do not provoke undefined behaviour, then
- *   assume that the error will be set on failure.</para></footnote>
+ *   assume that the error will be set on failure.
  *
  * - A %NULL return value is also frequently used to mean that an error
  *   occurred. You should make clear in your documentation whether %NULL
@@ -11940,7 +11937,7 @@
  * g_clear_error:
  * @err: a #GError return location
  *
- * If @err is %NULL, does nothing. If @err is non-%NULL,
+ * If @err or * err is %NULL, does nothing. Otherwise,
  * calls g_error_free() on * err and sets * err to %NULL.
  */
 
@@ -12514,7 +12511,7 @@
  * @oldval: (allow-none): the old value to compare against
  * @newval: (allow-none): the new value to replace it with
  * @destroy: (allow-none): destroy notify for the new value
- * @old_destroy: (optional) (out): destroy notify for the existing value
+ * @old_destroy: (allow-none): destroy notify for the existing value
  *
  * Compares the member that is associated with @key_id in
  * @datalist to @oldval, and if they are the same, replace
@@ -15670,8 +15667,8 @@
  * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
  * This is the directory
  * specified in the `XDG_RUNTIME_DIR` environment variable.
- * In the case that this variable is not set, GLib will issue a warning
- * message to stderr and return the value of g_get_user_cache_dir().
+ * In the case that this variable is not set, we return the value of
+ * g_get_user_cache_dir(), after verifying that it exists.
  *
  * On Windows this is the folder to use for local (as opposed to
  * roaming) application data. See documentation for
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 741928e..ebabda8 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -3141,7 +3141,7 @@
  * @oldval: (allow-none): the old value to compare against
  * @newval: (allow-none): the new value
  * @destroy: (allow-none): a destroy notify for the new value
- * @old_destroy: (optional) (out): destroy notify for the existing value
+ * @old_destroy: (allow-none): destroy notify for the existing value
  *
  * Compares the user data for the key @quark on @object with
  * @oldval, and if they are the same, replaces @oldval with