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

[Rico Tzschichholz <ricotz src gnome org>]

commit cf758608312525fb1826027757412f2b62e77f7f
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Sun Apr 22 10:51:13 2018 +0200

    gir: Update annotations from glib git master

 gir/gio-2.0.c     | 34 +++++++++++++++++++-------------
 gir/glib-2.0.c    | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 gir/gobject-2.0.c | 18 +++++++++++------
 3 files changed, 87 insertions(+), 24 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index b0406b89..8b2d34c1 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -2918,12 +2918,14 @@
 /**
  * GSimpleAction::activate:
  * @simple: the #GSimpleAction
- * @parameter: (nullable): the parameter to the activation
+ * @parameter: (nullable): the parameter to the activation, or %NULL if it has
+ *   no parameter
  *
  * Indicates that the action was just activated.
  *
- * @parameter will always be of the expected type.  In the event that
- * an incorrect type was given, no signal will be emitted.
+ * @parameter will always be of the expected type, i.e. the parameter type
+ * specified when the action was created. If an incorrect type is given when
+ * activating the action, this signal is not emitted.
  *
  * Since GLib 2.40, if no handler is connected to this signal then the
  * default behaviour for boolean-stated actions with a %NULL parameter
@@ -2945,8 +2947,10 @@
  * Indicates that the action just received a request to change its
  * state.
  *
- * @value will always be of the correct state type.  In the event that
- * an incorrect type was given, no signal will be emitted.
+ * @value will always be of the correct state type, i.e. the type of the
+ * initial state passed to g_simple_action_new_stateful(). If an incorrect
+ * type is given when requesting to change the state, this signal is not
+ * emitted.
  *
  * If no handler is connected to this signal then the default
  * behaviour is to call g_simple_action_set_state() to set the state
@@ -17135,7 +17139,7 @@
  * @cancellable: (nullable): a #GCancellable or %NULL
  * @error: return location for error or %NULL
  *
- * Synchronously closees @connection. The calling thread is blocked
+ * Synchronously closes @connection. The calling thread is blocked
  * until this is done. See g_dbus_connection_close() for the
  * asynchronous version of this method and more details about what it
  * does.
@@ -33728,8 +33732,7 @@
  * to call g_settings_get_child().
  *
  * For GSettings objects that are lists, this value can change at any
- * time and you should connect to the "children-changed" signal to watch
- * for those changes.  Note that there is a race condition here: you may
+ * time. Note that there is a race condition here: you may
  * request a child after listing it only for it to have been destroyed
  * in the meantime.  For this reason, g_settings_get_child() may return
  * %NULL even for a child that was listed by this function.
@@ -34695,11 +34698,13 @@
 /**
  * g_simple_action_new:
  * @name: the name of the action
- * @parameter_type: (nullable): the type of parameter to the activate function
+ * @parameter_type: (nullable): the type of parameter that will be passed to
+ *   handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
  *
  * Creates a new action.
  *
- * The created action is stateless.  See g_simple_action_new_stateful().
+ * The created action is stateless. See g_simple_action_new_stateful() to create
+ * an action that has state.
  *
  * Returns: a new #GSimpleAction
  * Since: 2.28
@@ -34709,15 +34714,16 @@
 /**
  * g_simple_action_new_stateful:
  * @name: the name of the action
- * @parameter_type: (nullable): the type of the parameter to the activate function
+ * @parameter_type: (nullable): the type of the parameter that will be passed to
+ *   handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
  * @state: the initial state of the action
  *
  * Creates a new stateful action.
  *
- * @state is the initial state of the action.  All future state values
- * must have the same #GVariantType as the initial state.
+ * All future state values must have the same #GVariantType as the initial
+ * @state.
  *
- * If the @state GVariant is floating, it is consumed.
+ * If the @state #GVariant is floating, it is consumed.
  *
  * Returns: a new #GSimpleAction
  * Since: 2.28
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index f9689fd3..a9cc893c 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -8350,10 +8350,17 @@
  * #GTimeZone is a structure that represents a time zone, at no
  * particular point in time.  It is refcounted and immutable.
  *
+ * Each time zone has an identifier (for example, ‘Europe/London’) which is
+ * platform dependent. See g_time_zone_new() for information on the identifier
+ * formats. The identifier of a time zone can be retrieved using
+ * g_time_zone_get_identifier().
+ *
  * A time zone contains a number of intervals.  Each interval has
- * an abbreviation to describe it, an offet to UTC and a flag indicating
- * if the daylight savings time is in effect during that interval.  A
- * time zone always has at least one interval -- interval 0.
+ * an abbreviation to describe it (for example, ‘PDT’), an offet to UTC and a
+ * flag indicating if the daylight savings time is in effect during that
+ * interval.  A time zone always has at least one interval — interval 0. Note
+ * that interval abbreviations are not the same as time zone identifiers
+ * (apart from ‘UTC’), and cannot be passed to g_time_zone_new().
  *
  * Every UTC time is contained within exactly one interval, but a given
  * local time may be contained within zero, one or two intervals (due to
@@ -14365,6 +14372,17 @@
  */
 
 
+/**
+ * g_date_time_get_timezone:
+ * @datetime: a #GDateTime
+ *
+ * Get the time zone for this @datetime.
+ *
+ * Returns: (transfer none): the time zone
+ * Since: 2.58
+ */
+
+
 /**
  * g_date_time_get_timezone_abbreviation:
  * @datetime: a #GDateTime
@@ -30340,7 +30358,7 @@
  * @str_array: a %NULL-terminated array of strings
  *
  * Returns the length of the given %NULL-terminated
- * string array @str_array.
+ * string array @str_array. @str_array must not be %NULL.
  *
  * Returns: length of @str_array.
  * Since: 2.6
@@ -31999,6 +32017,24 @@
  */
 
 
+/**
+ * g_time_zone_get_identifier:
+ * @tz: a #GTimeZone
+ *
+ * Get the identifier of this #GTimeZone, as passed to g_time_zone_new().
+ * If the identifier passed at construction time was not recognised, `UTC` will
+ * be returned. If it was %NULL, the identifier of the local timezone at
+ * construction time will be returned.
+ *
+ * The identifier will be returned in the same format as provided at
+ * construction time: if provided as a time offset, that will be returned by
+ * this function.
+ *
+ * Returns: identifier for this timezone
+ * Since: 2.58
+ */
+
+
 /**
  * g_time_zone_get_offset:
  * @tz: a #GTimeZone
@@ -32121,6 +32157,21 @@
  */
 
 
+/**
+ * g_time_zone_new_offset:
+ * @seconds: offset to UTC, in seconds
+ *
+ * Creates a #GTimeZone corresponding to the given constant offset from UTC,
+ * in seconds.
+ *
+ * This is equivalent to calling g_time_zone_new() with a string in the form
+ * `[+|-]hh[:mm[:ss]]`.
+ *
+ * Returns: (transfer full): a timezone at the given offset from UTC
+ * Since: 2.58
+ */
+
+
 /**
  * g_time_zone_new_utc:
  *
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 4e964e01..44b5761b 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -54,11 +54,17 @@
  * @gobject: the object which received the signal.
  * @pspec: the #GParamSpec of the property which changed.
  *
- * The notify signal is emitted on an object when one of its
- * properties has been changed. Note that getting this signal
- * doesn't guarantee that the value of the property has actually
- * changed, it may also be emitted when the setter for the property
- * is called to reinstate the previous value.
+ * The notify signal is emitted on an object when one of its properties has
+ * its value set through g_object_set_property(), g_object_set(), et al.
+ *
+ * Note that getting this signal doesn’t itself guarantee that the value of
+ * the property has actually changed. When it is emitted is determined by the
+ * derived GObject class. If the implementor did not create the property with
+ * %G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results
+ * in ::notify being emitted, even if the new value is the same as the old.
+ * If they did pass %G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only
+ * when they explicitly call g_object_notify() or g_object_notify_by_pspec(),
+ * and common practice is to avoid doing so if the value remained unchanged.
  *
  * This signal is typically used to obtain change notification for a
  * single property, by specifying the property name as a detail in the
@@ -3019,7 +3025,7 @@
 
 
 /**
- * g_object_new_with_properties: (rename-to g_object_new)
+ * g_object_new_with_properties: (skip)
  * @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