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

[Rico Tzschichholz <ricotz src gnome org>]

commit b010c1241227201581841122912f307d2311455a
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Mon Apr 9 08:04:41 2018 +0200

    gir: Update annotations from glib git master

 gir/gio-2.0.c  | 72 +++++++++++++++++++++++++++++++++++++++++++++-------------
 gir/glib-2.0.c | 35 ++++++++++++++++++++++------
 2 files changed, 84 insertions(+), 23 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index b8500132..b0406b89 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -5091,10 +5091,11 @@
  * instance and g_application_run() promptly returns. See the code
  * examples below.
  *
- * If used, the expected form of an application identifier is very close
- * to that of of a
- * [D-Bus bus 
name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface).
- * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
+ * If used, the expected form of an application identifier is the same as
+ * that of of a
+ * [D-Bus well-known bus 
name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
+ * Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`,
+ * `org._7_zip.Archiver`.
  * For details on valid application identifiers, see g_application_id_is_valid().
  *
  * On Linux, the application identifier is claimed as a well-known bus name
@@ -8854,9 +8855,16 @@
  * of server sockets and helps you accept sockets from any of the
  * socket, either sync or async.
  *
+ * Add addresses and ports to listen on using g_socket_listener_add_address()
+ * and g_socket_listener_add_inet_port(). These will be listened on until
+ * g_socket_listener_close() is called. Dropping your final reference to the
+ * #GSocketListener will not cause g_socket_listener_close() to be called
+ * implicitly, as some references to the #GSocketListener may be held
+ * internally.
+ *
  * If you want to implement a network server, also look at #GSocketService
- * and #GThreadedSocketService which are subclass of #GSocketListener
- * that makes this even easier.
+ * and #GThreadedSocketService which are subclasses of #GSocketListener
+ * that make this even easier.
  *
  * Since: 2.22
  */
@@ -11874,8 +11882,8 @@
  * The result is cached after it is generated the first time, and
  * the function is thread-safe.
  *
- * Returns: (transfer none): an object implementing
- *     @extension_point, or %NULL if there are no usable
+ * Returns: (transfer none): the type to instantiate to implement
+ *     @extension_point, or %G_TYPE_INVALID if there are no usable
  *     implementations.
  */
 
@@ -13675,23 +13683,47 @@
  * A valid ID is required for calls to g_application_new() and
  * g_application_set_application_id().
  *
+ * Application identifiers follow the same format as
+ * [D-Bus well-known bus 
names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
  * For convenience, the restrictions on application identifiers are
  * reproduced here:
  *
- * - Application identifiers must contain only the ASCII characters
- *   "[A-Z][a-z][0-9]_-." and must not begin with a digit.
+ * - Application identifiers are composed of 1 or more elements separated by a
+ *   period (`.`) character. All elements must contain at least one character.
  *
- * - Application identifiers must contain at least one '.' (period)
- *   character (and thus at least two elements).
+ * - Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`,
+ *   with `-` discouraged in new application identifiers. Each element must not
+ *   begin with a digit.
  *
- * - Application identifiers must not begin or end with a '.' (period)
- *   character.
+ * - Application identifiers must contain at least one `.` (period) character
+ *   (and thus at least two elements).
  *
- * - Application identifiers must not contain consecutive '.' (period)
- *   characters.
+ * - Application identifiers must not begin with a `.` (period) character.
  *
  * - Application identifiers must not exceed 255 characters.
  *
+ * Note that the hyphen (`-`) character is allowed in application identifiers,
+ * but is problematic or not allowed in various specifications and APIs that
+ * refer to D-Bus, such as
+ * [Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers),
+ * the
+ * [`DBusActivatable` interface in the Desktop Entry 
Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus),
+ * and the convention that an application's "main" interface and object path
+ * resemble its application identifier and bus name. To avoid situations that
+ * require special-case handling, it is recommended that new application
+ * identifiers consistently replace hyphens with underscores.
+ *
+ * Like D-Bus interface names, application identifiers should start with the
+ * reversed DNS domain name of the author of the interface (in lower-case), and
+ * it is conventional for the rest of the application identifier to consist of
+ * words run together, with initial capital letters.
+ *
+ * As with D-Bus interface names, if the author's DNS domain name contains
+ * hyphen/minus characters they should be replaced by underscores, and if it
+ * contains leading digits they should be escaped by prepending an underscore.
+ * For example, if the owner of 7-zip.org used an application identifier for an
+ * archiving application, it might be named `org._7_zip.Archiver`.
+ *
  * Returns: %TRUE if @application_id is valid
  */
 
@@ -36978,6 +37010,10 @@
  * requesting a binding to port 0 (ie: "any port").  This address, if
  * requested, belongs to the caller and must be freed.
  *
+ * Call g_socket_listener_close() to stop listening on @address; this will not
+ * be done automatically when you drop your final reference to @listener, as
+ * references may be held internally.
+ *
  * Returns: %TRUE on success, %FALSE on error.
  * Since: 2.22
  */
@@ -37022,6 +37058,10 @@
  * useful if you're listening on multiple addresses and do
  * different things depending on what address is connected to.
  *
+ * Call g_socket_listener_close() to stop listening on @port; this will not
+ * be done automatically when you drop your final reference to @listener, as
+ * references may be held internally.
+ *
  * Returns: %TRUE on success, %FALSE on error.
  * Since: 2.22
  */
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 56926fc0..f9689fd3 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -8491,7 +8491,7 @@
  *   i = (int) (long) p;
  * ]|
  * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
- * to do the right thing on the every platform.
+ * to do the right thing on every platform.
  *
  * Warning: You may not store pointers in integers. This is not
  * portable in any way, shape or form. These macros only allow storing
@@ -12282,8 +12282,8 @@
 /**
  * g_checksum_get_digest: (skip)
  * @checksum: a #GChecksum
- * @buffer: output buffer
- * @digest_len: an inout parameter. The caller initializes it to the size of @buffer.
+ * @buffer: (array length=digest_len): output buffer
+ * @digest_len: (inout): an inout parameter. The caller initializes it to the size of @buffer.
  *   After the call it contains the length of the digest.
  *
  * Gets the digest from @checksum as a raw binary vector and places it
@@ -16170,6 +16170,27 @@
  */
 
 
+/**
+ * g_get_language_names_with_category:
+ * @category_name: a locale category name
+ *
+ * Computes a list of applicable locale names with a locale category name,
+ * which can be used to construct the fallback locale-dependent filenames
+ * or search paths. The returned list is sorted from most desirable to
+ * least desirable and always contains the default locale "C".
+ *
+ * This function consults the environment variables `LANGUAGE`, `LC_ALL`,
+ * @category_name, and `LANG` to find the list of locales specified by the
+ * user.
+ *
+ * g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").
+ *
+ * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib
+ *    that must not be modified or freed.
+ * Since: 2.58
+ */
+
+
 /**
  * g_get_locale_variants:
  * @locale: a locale identifier
@@ -17067,8 +17088,8 @@
 /**
  * g_hmac_get_digest:
  * @hmac: a #GHmac
- * @buffer: output buffer
- * @digest_len: an inout parameter. The caller initializes it to the
+ * @buffer: (array length=digest_len): output buffer
+ * @digest_len: (inout): an inout parameter. The caller initializes it to the
  *   size of @buffer. After the call it contains the length of the digest
  *
  * Gets the digest from @checksum as a raw binary array and places it
@@ -32209,7 +32230,7 @@
  * context. You can do these steps manually if you need greater control or to
  * use a custom main context.
  *
- * The interval given in terms of monotonic time, not wall clock time.
+ * The interval given is in terms of monotonic time, not wall clock time.
  * See g_get_monotonic_time().
  *
  * Returns: the ID (greater than 0) of the event source.
@@ -32328,7 +32349,7 @@
  * The scheduling granularity/accuracy of this timeout source will be
  * in seconds.
  *
- * The interval given in terms of monotonic time, not wall clock time.
+ * The interval given is in terms of monotonic time, not wall clock time.
  * See g_get_monotonic_time().
  *
  * Returns: the newly-created timeout source