Update glib annotations from git master

3 files changed, 165 insertions, 43 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index bf3e229d..39b9e9f4 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -383,6 +383,16 @@
 
 
 /**
+ * GApplication:is-busy:
+ *
+ * Whether the application is currently marked as busy through
+ * g_application_mark_busy() or g_application_bind_busy_property().
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * GApplicationClass:
  * @startup: invoked on the primary instance immediately after registration
  * @shutdown: invoked only on the registered primary instance immediately
@@ -2708,6 +2718,29 @@
 
 
 /**
+ * GSimpleIOStream:
+ *
+ * A wrapper around a #GInputStream and a #GOutputStream.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GSimpleIOStream:input-stream:
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GSimpleIOStream:output-stream:
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * GSimplePermission:
  *
  * #GSimplePermission is an opaque data structure.  There are no methods
@@ -7289,6 +7322,25 @@
 
 
 /**
+ * SECTION:gsimpleiostream
+ * @short_description: A wrapper around an input and an output stream.
+ * @include: gio/gio.h
+ * @see_also: #GIOStream
+ *
+ * GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and
+ * #GOutputStream. This allows any pair of input and output streams to be used
+ * with #GIOStream methods.
+ *
+ * This is useful when you obtained a #GInputStream and a #GOutputStream
+ * by other means, for instance creating them with platform specific methods as
+ * g_unix_input_stream_new() or g_win32_input_stream_new(), and you want
+ * to take advantage of the methods provided by #GIOStream.
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * SECTION:gsimplepermission
  * @title: GSimplePermission
  * @short_description: A GPermission that doesn't change value
@@ -11805,6 +11857,23 @@
 
 
 /**
+ * g_application_bind_busy_property:
+ * @application: a #GApplication
+ * @object: a #GObject
+ * @property: the name of a boolean property of @object
+ *
+ * Marks @application as busy (see g_application_mark_busy()) while
+ * @property on @object is %TRUE.
+ *
+ * The binding holds a reference to @application while it is active, but
+ * not to @object. Instead, the binding is destroyed when @object is
+ * finalized.
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * g_application_command_line_create_file_for_arg:
  * @cmdline: a #GApplicationCommandLine
  * @arg: an argument from @cmdline
@@ -12157,6 +12226,18 @@
 
 
 /**
+ * g_application_get_is_busy:
+ * @application: a #GApplication
+ *
+ * Gets the application's current busy state, as set through
+ * g_application_mark_busy() or g_application_bind_busy_property().
+ *
+ * Returns: %TRUE if @application is currenty marked as busy
+ * Since: 2.44
+ */
+
+
+/**
  * g_application_get_is_registered:
  * @application: a #GApplication
  *
@@ -12442,11 +12523,7 @@
  * use.
  *
  * This function sets the prgname (g_set_prgname()), if not already set,
- * to the basename of argv[0].  Since 2.38, if %G_APPLICATION_IS_SERVICE
- * is specified, the prgname is set to the application ID.  The main
- * impact of this is is that the wmclass of windows created by Gtk+ will
- * be set accordingly, which helps the window manager determine which
- * application is showing the window.
+ * to the basename of argv[0].
  *
  * Since 2.40, applications that are not explicitly flagged as services
  * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
@@ -12629,6 +12706,20 @@
 
 
 /**
+ * g_application_unbind_busy_property:
+ * @application: a #GApplication
+ * @object: a #GObject
+ * @property: the name of a boolean property of @object
+ *
+ * Destroys a binding between @property and the busy state of
+ * @application that was previously created with
+ * g_application_bind_busy_property().
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * g_application_unmark_busy:
  * @application: a #GApplication
  *
@@ -24667,16 +24758,6 @@
 
 
 /**
- * g_input_stream_async_read_is_via_threads:
- * @stream: input stream
- *
- * Checks if an input stream's read_async function uses threads.
- *
- * Returns: %TRUE if @stream's read_async function uses threads.
- */
-
-
-/**
  * g_input_stream_clear_pending:
  * @stream: input stream
  *
@@ -28304,16 +28385,6 @@
 
 
 /**
- * g_output_stream_async_write_is_via_threads:
- * @stream: a #GOutputStream.
- *
- * Checks if an ouput stream's write_async function uses threads.
- *
- * Returns: %TRUE if @stream's write_async function uses threads.
- */
-
-
-/**
  * g_output_stream_clear_pending:
  * @stream: output stream
  *
@@ -32350,6 +32421,19 @@
 
 
 /**
+ * g_simple_io_stream_new:
+ * @input_stream: a #GInputStream.
+ * @output_stream: a #GOutputStream.
+ *
+ * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream.
+ * See also #GIOStream.
+ *
+ * Returns: a new #GSimpleIOStream instance.
+ * Since: 2.44
+ */
+
+
+/**
  * g_simple_permission_new:
  * @allowed: %TRUE if the action is allowed
  *
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 95c2f118..096432b8 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -14948,7 +14948,8 @@
 
 /**
  * g_get_charset:
- * @charset: return location for character set name
+ * @charset: (out) (optional) (transfer none): return location for character set
+ *   name, or %NULL.
  *
  * Obtains the character set for the [current locale][setlocale]; you
  * might use this character set as an argument to g_convert(), to convert
@@ -18499,7 +18500,8 @@
  *
  * This function iterates over the whole list to count its elements.
  * Use a #GQueue instead of a GList if you regularly need the number
- * of items.
+ * of items. To check whether the list is non-empty, it is faster to check
+ * @list against %NULL.
  *
  * Returns: the number of elements in the #GList
  */
@@ -21378,13 +21380,11 @@
 /**
  * g_option_context_add_group:
  * @context: a #GOptionContext
- * @group: the group to add
+ * @group: (transfer full): the group to add
  *
  * Adds a #GOptionGroup to the @context, so that parsing with @context
- * will recognize the options in the group. Note that the group will
- * be freed together with the context when g_option_context_free() is
- * called, so you must not free the group yourself after adding it
- * to a context.
+ * will recognize the options in the group. Note that this will take
+ * ownership of the @group and thus the @group should not be freed.
  *
  * Since: 2.6
  */
@@ -21479,9 +21479,9 @@
  *
  * Returns a pointer to the main group of @context.
  *
- * Returns: the main group of @context, or %NULL if @context doesn't
- *  have a main group. Note that group belongs to @context and should
- *  not be modified or freed.
+ * Returns: (transfer none): the main group of @context, or %NULL if
+ *  @context doesn't have a main group. Note that group belongs to
+ *  @context and should not be modified or freed.
  * Since: 2.6
  */
 
@@ -21658,7 +21658,7 @@
 /**
  * g_option_context_set_main_group:
  * @context: a #GOptionContext
- * @group: the group to set as main group
+ * @group: (transfer full): the group to set as main group
  *
  * Sets a #GOptionGroup as main group of the @context.
  * This has the same effect as calling g_option_context_add_group(),
@@ -21774,6 +21774,7 @@
  * which have been added to a #GOptionContext.
  *
  * Since: 2.6
+ * Deprecated: 2.44: Use g_option_group_unref() instead.
  */
 
 
@@ -21794,12 +21795,23 @@
  * Creates a new #GOptionGroup.
  *
  * Returns: a newly created option group. It should be added
- *   to a #GOptionContext or freed with g_option_group_free().
+ *   to a #GOptionContext or freed with g_option_group_unref().
  * Since: 2.6
  */
 
 
 /**
+ * g_option_group_ref:
+ * @group: a #GOptionGroup
+ *
+ * Increments the reference count of @group by one.
+ *
+ * Returns: a #GoptionGroup
+ * Since: 2.44
+ */
+
+
+/**
  * g_option_group_set_error_hook:
  * @group: a #GOptionGroup
  * @error_func: a function to call when an error occurs
@@ -21863,6 +21875,18 @@
 
 
 /**
+ * g_option_group_unref:
+ * @group: a #GOptionGroup
+ *
+ * Decrements the reference count of @group by one.
+ * If the reference count drops to 0, the @group will be freed.
+ * and all memory allocated by the @group is released.
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * g_parse_debug_string:
  * @string: (allow-none): a list of debug options separated by colons, spaces, or
  * commas, or %NULL.
@@ -25892,7 +25916,8 @@
  * Gets the number of elements in a #GSList.
  *
  * This function iterates over the whole list to
- * count its elements.
+ * count its elements. To check whether the list is non-empty, it is faster to
+ * check @list against %NULL.
  *
  * Returns: the number of elements in the #GSList
  */
@@ -28546,7 +28571,7 @@
  * g_test_add_data_func:
  * @testpath: /-separated test case path name for the test.
  * @test_data: Test data argument for the test function.
- * @test_func: The test function to invoke for this test.
+ * @test_func: (scope async): The test function to invoke for this test.
  *
  * Create a new test case, similar to g_test_create_case(). However
  * the test is assumed to use no fixture, and test suites are automatically
@@ -28579,7 +28604,7 @@
 /**
  * g_test_add_func:
  * @testpath: /-separated test case path name for the test.
- * @test_func: The test function to invoke for this test.
+ * @test_func: (scope async): The test function to invoke for this test.
  *
  * Create a new test case, similar to g_test_create_case(). However
  * the test is assumed to use no fixture, and test suites are automatically
@@ -28679,9 +28704,9 @@
  * @test_name: the name for the test case
  * @data_size: the size of the fixture data structure
  * @test_data: test data argument for the test functions
- * @data_setup: the function to set up the fixture data
- * @data_test: the actual test function
- * @data_teardown: the function to teardown the fixture data
+ * @data_setup: (scope async): the function to set up the fixture data
+ * @data_test: (scope async): the actual test function
+ * @data_teardown: (scope async): the function to teardown the fixture data
  *
  * Create a new #GTestCase, named @test_name, this API is fairly
  * low level, calling g_test_add() or g_test_add_func() is preferable.
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 676c4060..efe8981a 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -131,6 +131,19 @@
  * GObject ships with a utility called [glib-mkenums][glib-mkenums],
  * that can construct suitable type registration functions from C enumeration
  * definitions.
+ *
+ * Example of how to get a string representation of an enum value:
+ * |[<!-- language="C" -->
+ * GEnumClass *enum_class;
+ * GEnumValue *enum_value;
+ *
+ * enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM);
+ * enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO);
+ *
+ * g_print ("Name: %s\n", enum_value->value_name);
+ *
+ * g_type_class_unref (enum_class);
+ * ]|
  */