Update annotations from glib git

3 files changed, 155 insertions, 29 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index db413910..fa453370 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -5609,6 +5609,33 @@
 
 
 /**
+ * SECTION:gnetworking
+ * @title: gnetworking.h
+ * @short_description: System networking includes
+ * @include: gio/gnetworking.h
+ *
+ * The <literal>gnetworking.h</literal> header can be included to get
+ * various low-level networking-related system headers, automatically
+ * taking care of certain portability issues for you.
+ *
+ * This can be used, for example, if you want to call setsockopt()
+ * on a #GSocket.
+ *
+ * Note that while WinSock has many of the same APIs as the
+ * traditional UNIX socket API, most of them behave at least slightly
+ * differently (particularly with respect to error handling). If you
+ * want your code to work under both UNIX and Windows, you will need
+ * to take these differences into account.
+ *
+ * Also, under glibc, certain non-portable functions are only visible
+ * in the headers if you define <literal>_GNU_SOURCE</literal> before
+ * including them. Note that this symbol must be defined before
+ * including <emphasis>any</emphasis> headers, or it may not take
+ * effect.
+ */
+
+
+/**
  * SECTION:gnetworkmonitor
  * @title: GNetworkMonitor
  * @short_description: Network status monitor
@@ -6446,7 +6473,7 @@
  * SECTION:gsocket
  * @short_description: Low-level socket object
  * @include: gio/gio.h
- * @see_also: #GInitable
+ * @see_also: #GInitable, <link linkend="gio-gnetworking.h">gnetworking.h</link>
  *
  * A #GSocket is a low-level networking primitive. It is a more or less
  * direct mapping of the BSD socket API in a portable GObject based API.
@@ -18487,6 +18514,27 @@
 
 
 /**
+ * g_file_enumerator_get_child:
+ * @enumerator: a #GFileEnumerator
+ * @info: a #GFileInfo gotten from g_file_enumerator_next_file() or the async equivalents.
+ *
+ * Return a new #GFile which refers to the file named by @info in the source
+ * directory of @enumerator.  This function is primarily intended to be used
+ * inside loops with g_file_enumerator_next_file().
+ *
+ * This is a convenience method that's equivalent to:
+ * |[
+ *   gchar *name = g_file_info_get_name (info);
+ *   GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
+ *                                    name);
+ * ]|
+ *
+ * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
+ * Since: 2.36
+ */
+
+
+/**
  * g_file_enumerator_get_container:
  * @enumerator: a #GFileEnumerator
  *
@@ -21149,7 +21197,7 @@
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
- * Returns: %TRUE if there was any error, %FALSE otherwise.
+ * Returns: %FALSE if there was any error, %TRUE otherwise.
  */
 
 
@@ -24979,6 +25027,18 @@
 
 
 /**
+ * g_networking_init:
+ *
+ * Initializes the platform networking libraries (eg, on Windows, this
+ * calls WSAStartup()). GLib will call this itself if it is needed, so
+ * you only need to call it if you directly call system networking
+ * functions (without calling any GLib networking functions first).
+ *
+ * Since: 2.36
+ */
+
+
+/**
  * g_null_settings_backend_new:
  *
  * Creates a readonly #GSettingsBackend.
@@ -29836,6 +29896,34 @@
 
 
 /**
+ * g_socket_get_option:
+ * @socket: a #GSocket
+ * @level: the "API level" of the option (eg, <literal>SOL_SOCKET</literal>)
+ * @optname: the "name" of the option (eg, <literal>SO_BROADCAST</literal>)
+ * @value: (out): return location for the option value
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Gets the value of an integer-valued option on @socket, as with
+ * <literal>getsockopt ()</literal>. (If you need to fetch a
+ * non-integer-valued option, you will need to call
+ * <literal>getsockopt ()</literal> directly.)
+ *
+ * The <link linkend="gio-gnetworking.h"><literal>&lt;gio/gnetworking.h&gt;</literal></link>
+ * header pulls in system headers that will define most of the
+ * standard/portable socket options. For unusual socket protocols or
+ * platform-dependent options, you may need to include additional
+ * headers.
+ *
+ * Note that even for socket options that are a single byte in size,
+ * @value is still a pointer to a #gint variable, not a #guchar;
+ * g_socket_get_option() will handle the conversion internally.
+ *
+ * Returns: success or failure. On failure, @error will be set, and the system error value (<literal>errno</literal> or <literal>WSAGetLastError ()</literal>) will still be set to the result of the <literal>getsockopt ()</literal> call.
+ * Since: 2.36
+ */
+
+
+/**
  * g_socket_get_protocol:
  * @socket: a #GSocket.
  *
@@ -30699,6 +30787,30 @@
 
 
 /**
+ * g_socket_set_option:
+ * @socket: a #GSocket
+ * @level: the "API level" of the option (eg, <literal>SOL_SOCKET</literal>)
+ * @optname: the "name" of the option (eg, <literal>SO_BROADCAST</literal>)
+ * @value: the value to set the option to
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Sets the value of an integer-valued option on @socket, as with
+ * <literal>setsockopt ()</literal>. (If you need to set a
+ * non-integer-valued option, you will need to call
+ * <literal>setsockopt ()</literal> directly.)
+ *
+ * The <link linkend="gio-gnetworking.h"><literal>&lt;gio/gnetworking.h&gt;</literal></link>
+ * header pulls in system headers that will define most of the
+ * standard/portable socket options. For unusual socket protocols or
+ * platform-dependent options, you may need to include additional
+ * headers.
+ *
+ * Returns: success or failure. On failure, @error will be set, and the system error value (<literal>errno</literal> or <literal>WSAGetLastError ()</literal>) will still be set to the result of the <literal>setsockopt ()</literal> call.
+ * Since: 2.36
+ */
+
+
+/**
  * g_socket_set_timeout:
  * @socket: a #GSocket.
  * @timeout: the timeout for @socket, in seconds, or 0 for none
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index ec3aa02b..4c858e20 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -10975,7 +10975,7 @@
 
 
 /**
- * g_checksum_get_digest:
+ * 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. After the call it contains the length of the digest.
@@ -11024,7 +11024,7 @@
  * will be closed and it won't be possible to call g_checksum_update()
  * on it anymore.
  *
- * Returns: the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it.
+ * Returns: (transfer full): the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it.
  * Since: 2.16
  */
 
@@ -11053,7 +11053,7 @@
 /**
  * g_checksum_update:
  * @checksum: a #GChecksum
- * @data: buffer used to compute the checksum
+ * @data: (array length=length) (element-type guint8): buffer used to compute the checksum
  * @length: size of the buffer, or -1 if it is a null-terminated string.
  *
  * Feeds @data into an existing #GChecksum. The checksum must still be
@@ -11232,7 +11232,7 @@
 /**
  * g_compute_checksum_for_data:
  * @checksum_type: a #GChecksumType
- * @data: binary blob to compute the digest of
+ * @data: (array length=length) (element-type guint8): binary blob to compute the digest of
  * @length: length of @data
  *
  * Computes the checksum for a binary @data of @length. This is a
@@ -14516,31 +14516,31 @@
 /**
  * g_get_home_dir:
  *
- * Gets the current user's home directory as defined in the
- * password database.
+ * Gets the current user's home directory.
  *
- * Note that in contrast to traditional UNIX tools, this function
- * prefers <filename>passwd</filename> entries over the <envar>HOME</envar>
- * environment variable.
+ * As with most UNIX tools, this function will return the value of the
+ * <envar>HOME</envar> environment variable if it is set to an existing
+ * absolute path name, falling back to the <filename>passwd</filename>
+ * file in the case that it is unset.
  *
- * One of the reasons for this decision is that applications in many
- * cases need special handling to deal with the case where
- * <envar>HOME</envar> is
- * <simplelist>
- *   <member>Not owned by the user</member>
- *   <member>Not writeable</member>
- *   <member>Not even readable</member>
- * </simplelist>
- * Since applications are in general <emphasis>not</emphasis> written
- * to deal with these situations it was considered better to make
- * g_get_home_dir() not pay attention to <envar>HOME</envar> and to
- * return the real home directory for the user. If applications
- * want to pay attention to <envar>HOME</envar>, they can do:
- * |[
- *  const char *homedir = g_getenv ("HOME");
- *   if (!homedir)
- *      homedir = g_get_home_dir (<!-- -->);
- * ]|
+ * If the path given in <envar>HOME</envar> is non-absolute, does not
+ * exist, or is not a directory, the result is undefined.
+ *
+ * <note><para>
+ *   Before version 2.36 this function would ignore the
+ *   <envar>HOME</envar> environment variable, taking the value from the
+ *   <filename>passwd</filename> database instead.  This was changed to
+ *   increase the compatibility of GLib with other programs (and the XDG
+ *   basedir specification) and to increase testability of programs
+ *   based on GLib (by making it easier to run them from test
+ *   frameworks).
+ * </para><para>
+ *   If your program has a strong requirement for either the new or the
+ *   old behaviour (and if you don't wish to increase your GLib
+ *   dependency to ensure that the new behaviour is in effect) then you
+ *   should either directly check the <envar>HOME</envar> environment
+ *   variable yourself or unset it before calling any functions in GLib.
+ * </para></note>
  *
  * Returns: the current user's home directory
  */
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index fff5b1b0..fe54ac1c 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -4575,6 +4575,20 @@
 
 
 /**
+ * g_type_get_type_registration_serial:
+ *
+ * Returns an opaque serial number that represents the state of the set of registered
+ * types. Any time a type is registred this serial changes, which means you can
+ * cache information based on type lookups (such as g_type_from_name) and know if
+ * the cache is still valid at a later time by comparing the current serial with
+ * the one at the type lookup.
+ *
+ * Since: 2.36
+ * Returns: An unsigned int, representing the state of type registrations.
+ */
+
+
+/**
  * g_type_init:
  *
  * This function used to initialise the type system.  Since GLib 2.36,