Update annotations from glib git

3 files changed, 290 insertions, 27 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index d78bfdc6..5a92d00c 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -261,6 +261,13 @@
 
 
 /**
+ * GBytesIcon:bytes:
+ *
+ * The bytes containing the icon.
+ */
+
+
+/**
  * GCancellable::cancelled:
  * @cancellable: a #GCancellable.
  *
@@ -4018,6 +4025,19 @@
 
 
 /**
+ * SECTION:gbytesicon
+ * @short_description: An icon stored in memory as a #GBytes
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GLoadableIcon, #GBytes
+ *
+ * #GBytesIcon specifies an image held in memory in a common format (usually
+ * png) to be used as icon.
+ *
+ * Since: 2.38
+ */
+
+
+/**
  * SECTION:gcancellable
  * @short_description: Thread-safe Operation Cancellation Stack
  * @include: gio/gio.h
@@ -5247,12 +5267,22 @@
  *
  * To check if two #GIcons are equal, see g_icon_equal().
  *
- * For serializing a #GIcon, use g_icon_to_string() and
- * g_icon_new_for_string().
+ * For serializing a #GIcon, use g_icon_serialize() and
+ * g_icon_deserialize().
+ *
+ * If you want to consume #GIcon (for example, in a toolkit) you must
+ * be prepared to handle at least the three following cases:
+ * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon.  It may also make
+ * sense to have fast-paths for other cases (like handling #GdkPixbuf
+ * directly, for example) but all compliant #GIcon implementations
+ * outside of GIO must implement #GLoadableIcon.
  *
  * If your application or library provides one or more #GIcon
- * implementations you need to ensure that each #GType is registered
- * with the type system prior to calling g_icon_new_for_string().
+ * implementations you need to ensure that your new implementation also
+ * implements #GLoadableIcon.  Additionally, you must provide an
+ * implementation of g_icon_serialize() that gives a result that is
+ * understood by g_icon_deserialize(), yielding one of the built-in icon
+ * types.
  */
 
 
@@ -7641,7 +7671,7 @@
  * @include: gio/gio.h
  *
  * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
- * their certificate information from a file. It is in interface which
+ * their certificate information from a file. It is an interface which
  * TLS library specific subtypes implement.
  *
  * Since: 2.30
@@ -8548,6 +8578,38 @@
 
 
 /**
+ * g_action_parse_detailed_name:
+ * @detailed_name: a detailed action name
+ * @action_name: (out): the action name
+ * @target_value: (out): the target value, or %NULL for no target
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Parses a detailed action name into its separate name and target
+ * components.
+ *
+ * Detailed action names can have three formats.
+ *
+ * The first format is used to represent an action name with no target
+ * value and consists of just an action name containing no whitespace
+ * nor the characters ':', '(' or ')'.  For example: "app.action".
+ *
+ * The second format is used to represent an action with a string-typed
+ * target value.  The action name and target value are separated by a
+ * double colon ("::").  For example: "app.action::target".
+ *
+ * The third format is used to represent an action with an
+ * arbitrarily-typed target value.  The target value follows the action
+ * name, surrounded in parens.  For example: "app.action(42)".  The
+ * target value is parsed using g_variant_parse().  If a tuple-typed
+ * value is desired, it must be specified in the same way, resulting in
+ * two sets of parens, for example: "app.action((1,2,3))".
+ *
+ * Returns: %TRUE if successful, else %FALSE with @error set
+ * Since: 2.38
+ */
+
+
+/**
  * g_app_info_add_supports_type:
  * @appinfo: a #GAppInfo.
  * @content_type: a string.
@@ -9494,6 +9556,25 @@
 
 
 /**
+ * g_application_mark_busy:
+ * @application: a #GApplication
+ *
+ * Increases the busy count of @application.
+ *
+ * Use this function to indicate that the application is busy, for instance
+ * while a long running operation is pending.
+ *
+ * The busy state will be exposed to other processes, so a session shell will
+ * use that information to indicate the state to the user (e.g. with a
+ * spinner).
+ *
+ * To cancel the busy indication, use g_application_unmark_busy().
+ *
+ * Since: 2.38
+ */
+
+
+/**
  * g_application_new:
  * @application_id: (allow-none): the application id
  * @flags: the application flags
@@ -9770,6 +9851,22 @@
 
 
 /**
+ * g_application_unmark_busy:
+ * @application: a #GApplication
+ *
+ * Decreases the busy count of @application.
+ *
+ * When the busy count reaches zero, the new state will be propagated
+ * to other processes.
+ *
+ * This function must only be called to cancel the effect of a previous
+ * call to g_application_mark_busy().
+ *
+ * Since: 2.38
+ */
+
+
+/**
  * g_async_initable_init_async:
  * @initable: a #GAsyncInitable.
  * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
@@ -10501,6 +10598,28 @@
 
 
 /**
+ * g_bytes_icon_get_bytes:
+ * @icon: a #GIcon.
+ *
+ * Gets the #GBytes associated with the given @icon.
+ *
+ * Returns: (transfer none): a #GBytes, or %NULL.
+ * Since: 2.38
+ */
+
+
+/**
+ * g_bytes_icon_new:
+ * @bytes: a #GBytes.
+ *
+ * Creates a new icon for a bytes.
+ *
+ * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given @bytes, or %NULL on error.
+ * Since: 2.38
+ */
+
+
+/**
  * g_cancellable_cancel:
  * @cancellable: a #GCancellable object.
  *
@@ -12963,6 +13082,11 @@
  * tracking the name owner of the well-known name and use that when
  * processing the received signal.
  *
+ * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
+ * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is
+ * interpreted as part of a namespace or path.  The first argument
+ * of a signal is matched against that part as specified by D-Bus.
+ *
  * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
  * Since: 2.26
  */
@@ -17097,6 +17221,7 @@
  * Finishes deleting a file started with g_file_delete_async().
  *
  * Virtual: delete_file_finish
+ * Returns: %TRUE if the file was deleted. %FALSE otherwise.
  * Since: 2.34
  */
 
@@ -18717,6 +18842,36 @@
 
 
 /**
+ * g_file_make_directory_async:
+ * @file: input #GFile
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
+ *
+ * Asynchronously creates a directory.
+ *
+ * Virtual: make_directory_async
+ * Since: 2.38
+ */
+
+
+/**
+ * g_file_make_directory_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
+ *
+ * Finishes an asynchronous directory creation, started with
+ * g_file_make_directory_async().
+ *
+ * Virtual: make_directory_finish
+ * Returns: %TRUE on successful directory creation, %FALSE otherwise.
+ * Since: 2.38
+ */
+
+
+/**
  * g_file_make_directory_with_parents:
  * @file: input #GFile
  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
@@ -20196,7 +20351,38 @@
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
+ * Virtual: trash
+ * Returns: %TRUE on successful trash, %FALSE otherwise.
+ */
+
+
+/**
+ * g_file_trash_async:
+ * @file: input #GFile
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
+ *
+ * Asynchronously sends @file to the Trash location, if possible.
+ *
+ * Virtual: trash_async
+ * Since: 2.38
+ */
+
+
+/**
+ * g_file_trash_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
+ *
+ * Finishes an asynchronous file trashing operation, started with
+ * g_file_trash_async().
+ *
+ * Virtual: trash_finish
  * Returns: %TRUE on successful trash, %FALSE otherwise.
+ * Since: 2.38
  */
 
 
@@ -22632,14 +22818,8 @@
  *
  * Sets the "action" and possibly the "target" attribute of @menu_item.
  *
- * If @detailed_action contains a double colon ("::") then it is used as
- * a separator between an action name and a target string.  In this
- * case, this call is equivalent to calling
- * g_menu_item_set_action_and_target() with the part before the "::" and
- * with a string-type #GVariant containing the part following the "::".
- *
- * If @detailed_action doesn't contain "::" then the action is set to
- * the given string (verbatim) and the target value is unset.
+ * The format of @detailed_action is the same format parsed by
+ * g_action_parse_detailed_name().
  *
  * See g_menu_item_set_action_and_target() or
  * g_menu_item_set_action_and_target_value() for more flexible (but
@@ -22653,6 +22833,28 @@
 
 
 /**
+ * g_menu_item_set_icon:
+ * @menu_item: a #GMenuItem
+ * @icon: a #GIcon, or %NULL
+ *
+ * Sets (or unsets) the icon on @menu_item.
+ *
+ * This call is the same as calling g_icon_serialize() and using the
+ * result as the value to g_menu_item_set_attribute_value() for
+ * %G_MENU_ATTRIBUTE_ICON.
+ *
+ * This API is only intended for use with "noun" menu items; things like
+ * bookmarks or applications in an "Open With" menu.  Don't use it on
+ * menu items corresponding to verbs (eg: stock icons for 'Save' or
+ * 'Quit').
+ *
+ * If @icon is %NULL then the icon is unset.
+ *
+ * Since: 2.38
+ */
+
+
+/**
  * g_menu_item_set_label:
  * @menu_item: a #GMenuItem
  * @label: (allow-none): the label to set, or %NULL to unset
@@ -23032,6 +23234,16 @@
 
 
 /**
+ * g_menu_remove_all:
+ * @menu: a #GMenu
+ *
+ * Removes all items in the menu.
+ *
+ * Since: 2.38
+ */
+
+
+/**
  * g_mount_can_eject:
  * @mount: a #GMount.
  *
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index dc98af0d..7cf2ffa0 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -1898,7 +1898,7 @@
 /**
  * GTimeZone:
  *
- * #GDateTime is an opaque structure whose members cannot be accessed
+ * #GTimeZone is an opaque structure whose members cannot be accessed
  * directly.
  *
  * Since: 2.26
@@ -9827,9 +9827,9 @@
  * @bookmark: a #GBookmarkFile
  * @uri: a valid URI
  * @name: an application's name
- * @exec: (allow-none): location for the command line of the application, or %NULL
- * @count: (allow-none): return location for the registration count, or %NULL
- * @stamp: (allow-none): return location for the last registration time, or %NULL
+ * @exec: (allow-none) (out): return location for the command line of the application, or %NULL
+ * @count: (allow-none) (out): return location for the registration count, or %NULL
+ * @stamp: (allow-none) (out): return location for the last registration time, or %NULL
  * @error: return location for a #GError, or %NULL
  *
  * Gets the registration informations of @app_name for the bookmark for
@@ -9855,7 +9855,7 @@
  * g_bookmark_file_get_applications:
  * @bookmark: a #GBookmarkFile
  * @uri: a valid URI
- * @length: (allow-none): return location of the length of the returned list, or %NULL
+ * @length: (allow-none) (out): return location of the length of the returned list, or %NULL
  * @error: return location for a #GError, or %NULL
  *
  * Retrieves the names of the applications that have registered the
@@ -9864,7 +9864,7 @@
  * In the event the URI cannot be found, %NULL is returned and
  * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
  *
- * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
+ * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
  * Since: 2.12
  */
 
@@ -9889,7 +9889,7 @@
  * g_bookmark_file_get_groups:
  * @bookmark: a #GBookmarkFile
  * @uri: a valid URI
- * @length: (allow-none): return location for the length of the returned string, or %NULL
+ * @length: (allow-none) (out): return location for the length of the returned string, or %NULL
  * @error: return location for a #GError, or %NULL
  *
  * Retrieves the list of group names of the bookmark for @uri.
@@ -9900,7 +9900,7 @@
  * The returned array is %NULL terminated, so @length may optionally
  * be %NULL.
  *
- * Returns: a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it.
+ * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it.
  * Since: 2.12
  */
 
@@ -9909,8 +9909,8 @@
  * g_bookmark_file_get_icon:
  * @bookmark: a #GBookmarkFile
  * @uri: a valid URI
- * @href: (allow-none): return location for the icon's location or %NULL
- * @mime_type: (allow-none): return location for the icon's MIME type or %NULL
+ * @href: (allow-none) (out): return location for the icon's location or %NULL
+ * @mime_type: (allow-none) (out): return location for the icon's MIME type or %NULL
  * @error: return location for a #GError or %NULL
  *
  * Gets the icon of the bookmark for @uri.
@@ -10007,13 +10007,13 @@
 /**
  * g_bookmark_file_get_uris:
  * @bookmark: a #GBookmarkFile
- * @length: (allow-none): return location for the number of returned URIs, or %NULL
+ * @length: (allow-none) (out): return location for the number of returned URIs, or %NULL
  *
  * Returns all URIs of the bookmarks in the bookmark file @bookmark.
  * The array of returned URIs will be %NULL-terminated, so @length may
  * optionally be %NULL.
  *
- * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
+ * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
  * Since: 2.12
  */
 
@@ -10412,7 +10412,7 @@
 /**
  * g_bookmark_file_to_data:
  * @bookmark: a #GBookmarkFile
- * @length: (allow-none): return location for the length of the returned string, or %NULL
+ * @length: (allow-none) (out): return location for the length of the returned string, or %NULL
  * @error: return location for a #GError, or %NULL
  *
  * This function outputs @bookmark as a string.
@@ -32283,7 +32283,7 @@
  *
  * A reference is taken on @bytes.
  *
- * Returns: a new #GVariant with a floating reference
+ * Returns: (transfer none): a new #GVariant with a floating reference
  * Since: 2.36
  */
 
@@ -32532,6 +32532,26 @@
 
 
 /**
+ * g_variant_new_take_string: (skip)
+ * @string: a normal utf8 nul-terminated string
+ *
+ * Creates a string #GVariant with the contents of @string.
+ *
+ * @string must be valid utf8.
+ *
+ * This function consumes @string.  g_free() will be called on @string
+ * when it is no longer required.
+ *
+ * You must not modify or access @string in any other way after passing
+ * it to this function.  It is even possible that @string is immediately
+ * freed.
+ *
+ * Returns: (transfer none): a floating reference to a new string #GVariant instance
+ * Since: 2.38
+ */
+
+
+/**
  * g_variant_new_tuple:
  * @children: (array length=n_children): the items to make the tuple out of
  * @n_children: the length of @children
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 05d5ee09..3f568826 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -2698,6 +2698,19 @@
 
 
 /**
+ * g_param_get_default_value:
+ * @param: a #GParamSpec
+ *
+ * Gets the default value of @param as a pointer to a #GValue.
+ *
+ * The #GValue will remain value for the life of @param.
+ *
+ * Returns: a pointer to a #GValue which must not be modified
+ * Since: 2.38
+ */
+
+
+/**
  * g_param_spec_boolean:
  * @name: canonical name of the property specified
  * @nick: nick name for the property specified
@@ -4320,6 +4333,24 @@
 
 
 /**
+ * g_type_class_get_instance_private_offset: (skip)
+ * @g_class: a #GTypeClass
+ *
+ * Gets the offset of the private data for instances of @g_class.
+ *
+ * This is how many bytes you should add to the instance pointer of a
+ * class in order to get the private data for the type represented by
+ * @g_class.
+ *
+ * You can only call this function after you have registered a private
+ * data area for @g_class using g_type_class_add_private().
+ *
+ * Returns: the offset, in bytes
+ * Since: 2.38
+ */
+
+
+/**
  * g_type_class_peek:
  * @type: Type ID of a classed type.
  *