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

[Rico Tzschichholz <ricotz src gnome org>]

commit 24492500027695cccbd30d7369214b4de06304c2
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Wed Apr 20 13:44:56 2016 +0200

    gir: Update annotations from GLib git master

 gir/gio-2.0.c     |   19 +++++++++----------
 gir/glib-2.0.c    |   52 +++++++++++++++++++++++++++++++++++++++++-----------
 gir/gobject-2.0.c |    2 +-
 3 files changed, 51 insertions(+), 22 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index fc47538..5827a2a 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -401,11 +401,11 @@
  * @open: invoked on the primary instance when there are files to open
  * @command_line: invoked on the primary instance when a command-line is
  *   not handled locally
- * @local_command_line: invoked (locally) when the process has been invoked
- *     via commandline execution (as opposed to, say, D-Bus activation - which
- *     is not currently supported by GApplication). The virtual function has
- *     the chance to inspect (and possibly replace) the list of command line
- *     arguments. See g_application_run() for more information.
+ * @local_command_line: invoked (locally). The virtual function has the chance
+ *     to inspect (and possibly replace) command line arguments. See
+ *     g_application_run() for more information. Also see the
+ *     #GApplication::handle-local-options signal, which is a simpler
+ *     alternative to handling some commandline options locally
  * @before_emit: invoked on the primary instance before 'activate', 'open',
  *     'command-line' or any action invocation, gets the 'platform data' from
  *     the calling instance
@@ -432,7 +432,7 @@
  *     is using its D-Bus backend. Use this to undo anything done by the
  *     @dbus_register vfunc. Since: 2.34
  * @handle_local_options: invoked locally after the parsing of the commandline
- *  options has occurred.
+ *  options has occurred. Since: 2.40
  *
  * Virtual function table for #GApplication.
  *
@@ -11859,10 +11859,9 @@
  *
  * It is an error to call this function with an invalid action name.
  *
- * This function is the opposite of
- * g_action_parse_detailed_action_name().  It will produce a string that
- * can be parsed back to the @action_name and @target_value by that
- * function.
+ * This function is the opposite of g_action_parse_detailed_name().
+ * It will produce a string that can be parsed back to the @action_name
+ * and @target_value by that function.
  *
  * See that function for the types of strings that will be printed by
  * this function.
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index c91dddd..9fc4beb 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -1029,7 +1029,7 @@
  *            various functions such as g_io_channel_write_chars() to
  *            write raw bytes to the channel.  Encoding and buffering
  *            issues are dealt with at a higher level.
- * @io_seek: &lpar;optional&rpar; seeks the channel.  This is called from
+ * @io_seek: (optional): seeks the channel.  This is called from
  *           g_io_channel_seek() on channels that support it.
  * @io_close: closes the channel.  This is called from
  *            g_io_channel_close() after flushing the buffers.
@@ -5418,13 +5418,13 @@
  * "Presentaci&oacute;n.sxi". If the application which created it uses
  * ISO-8859-1 for its encoding,
  * |[
- * Character:  P  r  e  s  e  n  t  a  c  i  &oacute;  n  .  s  x  i
+ * Character:  P  r  e  s  e  n  t  a  c  i  ó  n  .  s  x  i
  * Hex code:   50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
  * ]|
  * However, if the application use UTF-8, the actual file name on
  * disk would look like this:
  * |[
- * Character:  P  r  e  s  e  n  t  a  c  i  &oacute;     n  .  s  x  i
+ * Character:  P  r  e  s  e  n  t  a  c  i  ó     n  .  s  x  i
  * Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
  * ]|
  * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
@@ -6076,7 +6076,7 @@
  * Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
  * to these functions must be encoded in UTF-8. The lengths and the positions
  * inside the strings are in bytes and not in characters, so, for instance,
- * "\xc3\xa0" (i.e. "&agrave;") is two bytes long but it is treated as a
+ * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
  * single character. If you set #G_REGEX_RAW the strings can be non-valid
  * UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
  * bytes and two characters long.
@@ -6159,10 +6159,36 @@
  * @short_description: strongly typed value datatype
  * @see_also: GVariantType
  *
- * #GVariant is a variant datatype; it stores a value along with
- * information about the type of that value.  The range of possible
- * values is determined by the type.  The type system used by #GVariant
- * is #GVariantType.
+ * #GVariant is a variant datatype; it can contain one or more values
+ * along with information about the type of the values.
+ *
+ * A #GVariant may contain simple types, like an integer, or a boolean value;
+ * or complex types, like an array of two strings, or a dictionary of key
+ * value pairs. A #GVariant is also immutable: once it's been created neither
+ * its type nor its content can be modified further.
+ *
+ * GVariant is useful whenever data needs to be serialized, for example when
+ * sending method parameters in DBus, or when saving settings using GSettings.
+ *
+ * When creating a new #GVariant, you pass the data you want to store in it
+ * along with a string representing the type of data you wish to pass to it.
+ *
+ * For instance, if you want to create a #GVariant holding an integer value you
+ * can use:
+ *
+ * |[<!-- language="C" -->
+ *   GVariant *v = g_variant_new ('u', 40);
+ * ]|
+ *
+ * The string 'u' in the first argument tells #GVariant that the data passed to
+ * the constructor (40) is going to be an unsigned integer.
+ *
+ * More advanced examples of #GVariant in use can be found in documentation for
+ * [GVariant format strings][gvariant-format-strings-pointers].
+ *
+ * The range of possible values is determined by the type.
+ *
+ * The type system used by #GVariant is #GVariantType.
  *
  * #GVariant instances always have a type and a value (which are given
  * at construction time).  The type and value of a #GVariant instance
@@ -12993,7 +13019,7 @@
  * @date: a #GDate
  *
  * Returns the week of the year during which this date falls, if
- * weeks are understood to being on Sunday. The date must be valid.
+ * weeks are understood to begin on Sunday. The date must be valid.
  * Can return 0 if the day is before the first Sunday of the year.
  *
  * Returns: week number
@@ -15305,7 +15331,7 @@
  * and said environment variables have no effect.
  *
  * `G_FILENAME_ENCODING` may be set to a comma-separated list of
- * character set names. The special token "&commat;locale" is taken
+ * character set names. The special token "\ locale" is taken
  * to  mean the character set for the [current locale][setlocale].
  * If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
  * the character set of the current locale is taken as the filename
@@ -27960,7 +27986,7 @@
  * @exceptions: (nullable): a string of characters not to escape in @source
  *
  * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
- * and '&quot;' in the string @source by inserting a '\' before
+ * and '"' in the string @source by inserting a '\' before
  * them. Additionally all characters in the range 0x01-0x1F (everything
  * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
  * replaced with a '\' followed by their octal representation.
@@ -28626,6 +28652,10 @@
  * optional @separator inserted between each of them. The returned string
  * should be freed with g_free().
  *
+ * If @str_array has no items, the return value will be an
+ * empty string. If @str_array contains a single item, @separator will not
+ * appear in the resulting string.
+ *
  * Returns: a newly-allocated string containing all of the strings joined
  *     together, with @separator between them
  */
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index ebabda8..37f7acd 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -6014,7 +6014,7 @@
 /**
  * g_value_array_insert:
  * @value_array: #GValueArray to add an element to
- * @index_: insertion position, must be <= value_array-&gt;n_values
+ * @index_: insertion position, must be <= value_array->;n_values
  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
  *
  * Insert a copy of @value at specified position into @value_array. If @value