From 1328045bb953e40b1978a43f180da119dc490dc3 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Sun, 8 Dec 2013 13:57:51 +0100 Subject: Update glib annotations from git master --- gir/gio-2.0.c | 70 ++++++++++++++++++++++++++++++++++++++++++++----------- gir/glib-2.0.c | 29 +++++++++++++++-------- gir/gobject-2.0.c | 6 ++--- 3 files changed, 78 insertions(+), 27 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 4ca1f234..0af69ab2 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -343,7 +343,7 @@ * An example of how to us this: * |[ * /* Make sure we don't do any unnecessary work if already cancelled */ - * if (g_cancellable_set_error_if_cancelled (cancellable)) + * if (g_cancellable_set_error_if_cancelled (cancellable, error)) * return; * * /* Set up all the data needed to be able to @@ -2692,7 +2692,7 @@ /** * GTestDBus:flags: * - * #GTestDBusFlags specifying the behaviour of the dbus session + * #GTestDBusFlags specifying the behaviour of the D-Bus session. * * Since: 2.34 */ @@ -7509,7 +7509,7 @@ * bd->cake = cake; * * /* Bail out now if the user has already cancelled */ - * if (g_task_return_error_if_cancelled (g_task_get_cancellable (task))) + * if (g_task_return_error_if_cancelled (task)) * { * g_object_unref (task); * return; @@ -7867,6 +7867,12 @@ * A helper class for testing code which uses D-Bus without touching the user's * session bus. * + * Note that #GTestDBus modifies the user’s environment, calling setenv(). This + * is not thread-safe, so all #GTestDBus calls should be completed before + * threads are spawned, or should have appropriate locking to ensure no access + * conflicts to environment variables shared between #GTestDBus and other + * threads. + * * * Creating unit tests using GTestDBus * @@ -7879,13 +7885,15 @@ * * * The first thing you will need is a separate service description file for the - * D-Bus daemon. Typically a 'services' subdirectory of your 'tests' directory + * D-Bus daemon. Typically a services subdirectory of + * your tests directory * is a good place to put this file. * * * The service file should list your service along with an absolute path to the * uninstalled service executable in your source tree. Using autotools we would - * achieve this by adding a file such as 'my-server.service.in' in the services + * achieve this by adding a file such as my-server.service.in + * in the services * directory and have it processed by configure. * * [D-BUS Service] @@ -7902,7 +7910,7 @@ * * * Once you have a service definition file which is local to your source tree, - * you can proceed to setup a GTest fixture using the GTestDBus scaffolding. + * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. * * Test Fixture for D-Bus services * @@ -7923,10 +7931,10 @@ * * * Most of the time we can work around these obstacles using the environment. Since the - * environment is inherited by the D-Bus daemon created by GTestDBus and then in turn + * environment is inherited by the D-Bus daemon created by #GTestDBus and then in turn * inherited by any services the D-Bus daemon activates, using the setup routine for your * fixture is a practical place to help sandbox your runtime environment. For the rather - * typical GSettings case we can work around this by setting GSETTINGS_SCHEMA_DIR to the + * typical GSettings case we can work around this by setting GSETTINGS_SCHEMA_DIR to the * in tree directory holding your schemas in the above fixture_setup() routine. * * @@ -22529,6 +22537,35 @@ * * If @make_backup is %TRUE, this function will attempt to * make a backup of @file. + * + * No copy of @content will be made, so it must stay valid until + * @callback is called. See g_file_replace_contents_bytes_async() for a #GBytes + * version that will automatically hold a reference to the contents (without + * copying) for the duration of the call. + */ + + +/** + * g_file_replace_contents_bytes_async: + * @file: input #GFile + * @contents: a #GBytes + * @etag: (allow-none): a new entity tag for the @file, or %NULL + * @make_backup: %TRUE if a backup should be created + * @flags: a set of #GFileCreateFlags + * @cancellable: 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 + * + * Same as g_file_replace_contents_async() but takes a #GBytes input instead. + * This function will keep a ref on @contents until the operation is done. + * Unlike g_file_replace_contents_async() this allows forgetting about the + * content without waiting for the callback. + * + * When this operation has completed, @callback will be called with + * @user_user data, and the operation can be finalized with + * g_file_replace_contents_finish(). + * + * Since: 2.40 */ @@ -27552,6 +27589,11 @@ * * For the synchronous, blocking version of this function, see * g_output_stream_write(). + * + * No copy of @buffer will be made, so it must stay valid until + * @callback is called. See g_output_stream_write_bytes_async() for a #GBytes + * version that will automatically hold a reference to the contents (without + * copying) for the duration of the call. */ @@ -34364,7 +34406,7 @@ /** * g_subprocess_newv: (rename-to g_subprocess_new) - * @argv: commandline arguments for the subprocess + * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess * @flags: flags that define the behaviour of the subprocess * @error: (allow-none): return location for an error, or %NULL * @@ -35078,7 +35120,7 @@ * @self: a #GTestDBus * @path: path to a directory containing .service files * - * Add a path where dbus-daemon will lookup for .services files. This can't be + * Add a path where dbus-daemon will look up .service files. This can't be * called after g_test_dbus_up(). */ @@ -35099,11 +35141,11 @@ * g_test_dbus_get_bus_address: * @self: a #GTestDBus * - * Get the address on which dbus-daemon is running. if g_test_dbus_up() has not + * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not * been called yet, %NULL is returned. This can be used with - * g_dbus_connection_new_for_address() + * g_dbus_connection_new_for_address(). * - * Returns: the address of the bus, or %NULL. + * Returns: (allow-none): the address of the bus, or %NULL. */ @@ -35111,7 +35153,7 @@ * g_test_dbus_get_flags: * @self: a #GTestDBus * - * Gets the flags of the #GTestDBus object. + * Get the flags of the #GTestDBus object. * * Returns: the value of #GTestDBus:flags property */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index c0c7febf..885afd01 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -100,8 +100,8 @@ /** * GBytes: * - * A simple refcounted data type representing an immutable byte sequence - * from an unspecified origin. + * A simple refcounted data type representing an immutable sequence of zero or + * more bytes from an unspecified origin. * * The purpose of a #GBytes is to keep the memory region that it holds * alive for as long as anyone holds a reference to the bytes. When @@ -11187,8 +11187,12 @@ * * This function will always return the same pointer for a given #GBytes. * - * Returns: (transfer none) (array length=size) (type guint8): a pointer to the - * byte data + * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes + * may represent an empty string with @data non-%NULL and @size as 0. %NULL will + * not be returned if @size is non-zero. + * + * Returns: (transfer none) (array length=size) (type guint8) (allow-none): a pointer to the + * byte data, or %NULL * Since: 2.32 */ @@ -11222,13 +11226,13 @@ /** * g_bytes_new: - * @data: (transfer none) (array length=size) (element-type guint8): + * @data: (transfer none) (array length=size) (element-type guint8) (allow-none): * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from @data. * - * @data is copied. + * @data is copied. If @size is 0, @data may be %NULL. * * Returns: (transfer full): a new #GBytes * Since: 2.32 @@ -11254,13 +11258,14 @@ /** * g_bytes_new_static: (skip) - * @data: (transfer full) (array length=size) (element-type guint8): + * @data: (transfer full) (array length=size) (element-type guint8) (allow-none): * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from static data. * - * @data must be static (ie: never modified or freed). + * @data must be static (ie: never modified or freed). It may be %NULL if @size + * is 0. * * Returns: (transfer full): a new #GBytes * Since: 2.32 @@ -11269,7 +11274,7 @@ /** * g_bytes_new_take: - * @data: (transfer full) (array length=size) (element-type guint8): + * @data: (transfer full) (array length=size) (element-type guint8) (allow-none): * the data to be used for the bytes * @size: the size of @data * @@ -11284,6 +11289,8 @@ * For creating #GBytes with memory from other allocators, see * g_bytes_new_with_free_func(). * + * @data may be %NULL if @size is 0. + * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ @@ -11291,7 +11298,7 @@ /** * g_bytes_new_with_free_func: - * @data: (array length=size): the data to be used for the bytes + * @data: (array length=size) (allow-none): the data to be used for the bytes * @size: the size of @data * @free_func: the function to call to release the data * @user_data: data to pass to @free_func @@ -11304,6 +11311,8 @@ * @data must not be modified after this call is made until @free_func has * been called to indicate that the bytes is no longer in use. * + * @data may be %NULL if @size is 0. + * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 89c083cb..a5cd41ab 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -3719,7 +3719,7 @@ * * Connects a closure to a signal for a particular object. * - * Returns: the handler id + * Returns: the handler id (always greater than 0 for successful connections) */ @@ -3734,7 +3734,7 @@ * * Connects a closure to a signal for a particular object. * - * Returns: the handler id + * Returns: the handler id (always greater than 0 for successful connections) */ @@ -3753,7 +3753,7 @@ * used. Specify @connect_flags if you need ..._after() or * ..._swapped() variants of this function. * - * Returns: the handler id + * Returns: the handler id (always greater than 0 for successful connections) */ -- cgit v1.2.1