From dec574dfdeb971736003738696f09c40b7911c64 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Thu, 19 Feb 2015 14:07:13 +0100 Subject: Update glib annotations from git master --- gir/gio-2.0.c | 134 ++++++++++++++++++++++++++++++++++++++++++++---------- gir/glib-2.0.c | 61 +++++++++++++++++-------- gir/gobject-2.0.c | 13 ++++++ 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 @@ -382,6 +382,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 @@ -2707,6 +2717,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: * @@ -7288,6 +7321,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 @@ -11804,6 +11856,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 @@ -12156,6 +12225,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 @@ -12628,6 +12705,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 @@ -24666,16 +24757,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 @@ -28303,16 +28384,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 @@ -32349,6 +32420,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,11 +21795,22 @@ * 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 @@ -21862,6 +21874,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 @@ -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: + * |[ + * 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); + * ]| */ -- cgit v1.2.1