From 17c3480012c0d824e689da4fa4d7b016a4e5a2bc Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Wed, 11 Oct 2017 17:19:56 +0200 Subject: gir: Update annotations from GLib git master --- gir/gio-2.0.c | 30 +++++++---- gir/glib-2.0.c | 155 ++++++++++++++++++++++++++++++++++++++++++++++-------- gir/gobject-2.0.c | 8 +-- 3 files changed, 156 insertions(+), 37 deletions(-) (limited to 'gir') diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 84bd79bb..615e4966 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -2162,9 +2162,12 @@ * GMount::pre-unmount: * @mount: the object on which the signal is emitted * - * This signal is emitted when the #GMount is about to be + * This signal may be emitted when the #GMount is about to be * unmounted. * + * This signal depends on the backend and is only emitted if + * GIO was used to unmount. + * * Since: 2.22 */ @@ -4105,7 +4108,10 @@ * @volume_monitor: The volume monitor emitting the signal. * @mount: a #GMount that is being unmounted. * - * Emitted when a mount is about to be removed. + * May be emitted when a mount is about to be removed. + * + * This signal depends on the backend and is only emitted if + * GIO was used to unmount. */ @@ -8298,7 +8304,7 @@ * ... * * plugin->schema_source = - * g_settings_new_schema_source_from_directory (dir, + * g_settings_schema_source_new_from_directory (dir, * g_settings_schema_source_get_default (), FALSE, NULL); * * ... @@ -14269,8 +14275,8 @@ * * Gets the source object from a #GAsyncResult. * - * Returns: (transfer full): a new reference to the source object for the @res, - * or %NULL if there is none. + * Returns: (transfer full) (nullable): a new reference to the source + * object for the @res, or %NULL if there is none. */ @@ -24433,9 +24439,11 @@ * g_file_load_partial_contents_async: (skip) * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore - * @read_more_callback: a #GFileReadMoreCallback to receive partial data + * @read_more_callback: (scope call) (closure user_data): a + * #GFileReadMoreCallback to receive partial data * and to specify whether further data should be read - * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: the data to pass to the callback functions * * Reads the partial contents of a file. A #GFileReadMoreCallback should @@ -25853,7 +25861,7 @@ * * Sets an attribute in the file with attribute name @attribute to @value. * - * Some attributes can be unset by setting @attribute to + * Some attributes can be unset by setting @type to * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. * * If @cancellable is not %NULL, then the operation can be cancelled by @@ -33961,7 +33969,7 @@ * lookups performed against the default source should probably be done * recursively. * - * Returns: (transfer none): the default schema source + * Returns: (transfer none) (nullable): the default schema source * Since: 2.32 */ @@ -36408,7 +36416,7 @@ * @socket: a #GSocket. * @error: #GError for error reporting, or %NULL to ignore. * - * Try to get the remove address of a connected socket. This is only + * Try to get the remote address of a connected socket. This is only * useful for connection oriented sockets that have been connected. * * Returns: (transfer full): a #GSocketAddress or %NULL on error. @@ -38582,7 +38590,7 @@ * Gets the source object from @task. Like * g_async_result_get_source_object(), but does not ref the object. * - * Returns: (transfer none) (type GObject): @task's source object, or %NULL + * Returns: (transfer none) (nullable) (type GObject): @task's source object, or %NULL * Since: 2.36 */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 0b3e7819..ce126e04 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -4182,19 +4182,27 @@ /** * G_LOG_DOMAIN: * - * Defines the log domain. + * Defines the log domain. See [Log Domains](#log-domains). * * Libraries should define this so that any messages * which they log can be differentiated from messages from other * libraries and application code. But be careful not to define * it in any public header files. * - * For example, GTK+ uses this in its Makefile.am: + * Log domains must be unique, and it is recommended that they are the + * application or library name, optionally followed by a hyphen and a sub-domain + * name. For example, `bloatpad` or `bloatpad-io`. + * + * If undefined, it defaults to the default %NULL (or `""`) log domain; this is + * not advisable, as it cannot be filtered against using the `G_MESSAGES_DEBUG` + * environment variable. + * + * For example, GTK+ uses this in its `Makefile.am`: * |[ * AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\" * ]| * - * Applications can choose to leave it as the default %NULL (or "") + * Applications can choose to leave it as the default %NULL (or `""`) * domain. However, defining the domain offers the same advantages as * above. */ @@ -6820,7 +6828,7 @@ * are optional. * Space before and after the '=' character are ignored. Newline, tab, * carriage return and backslash characters in value are escaped as \n, - * \t, \r, and \\, respectively. To preserve leading spaces in values, + * \t, \r, and \\\\, respectively. To preserve leading spaces in values, * these can also be escaped as \s. * * Key files can store strings (possibly with localized variants), integers, @@ -7891,7 +7899,7 @@ * duplicating, and manipulating strings. * * Note that the functions g_printf(), g_fprintf(), g_sprintf(), - * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() + * g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf() * are declared in the header `gprintf.h` which is not included in `glib.h` * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to * explicitly include `` in order to use the GLib @@ -7980,10 +7988,6 @@ * variants over plain g_assert() is that the assertion messages can be * more elaborate, and include the values of the compared entities. * - * GLib ships with two utilities called [gtester][gtester] and - * [gtester-report][gtester-report] to facilitate running tests and producing - * nicely formatted test reports. - * * A full example of creating a test suite with two tests using fixtures: * |[ * #include @@ -8047,6 +8051,78 @@ * return g_test_run (); * } * ]| + * + * ### Integrating GTest in your project + * + * If you are using the [Meson](http://mesonbuild.com) build system, you will + * typically use the provided `test()` primitive to call the test binaries, + * e.g.: + * + * |[ + * test( + * 'foo', + * executable('foo', 'foo.c', dependencies: deps), + * env: [ + * 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), + * 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), + * ], + * ) + * + * test( + * 'bar', + * executable('bar', 'bar.c', dependencies: deps), + * env: [ + * 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), + * 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), + * ], + * ) + * ]| + * + * If you are using Autotools, you're strongly encouraged to use the Automake + * [TAP](https://testanything.org/) harness; GLib provides template files for + * easily integrating with it: + * + * - [glib-tap.mk](https://git.gnome.org/browse/glib/tree/glib-tap.mk) + * - [tap-test](https://git.gnome.org/browse/glib/tree/tap-test) + * - [tap-driver.sh](https://git.gnome.org/browse/glib/tree/tap-driver.sh) + * + * You can copy these files in your own project's root directory, and then + * set up your `Makefile.am` file to reference them, for instance: + * + * |[ + * include $(top_srcdir)/glib-tap.mk + * + * # test binaries + * test_programs = \ + * foo \ + * bar + * + * # data distributed in the tarball + * dist_test_data = \ + * foo.data.txt \ + * bar.data.txt + * + * # data not distributed in the tarball + * test_data = \ + * blah.data.txt + * ]| + * + * Make sure to distribute the TAP files, using something like the following + * in your top-level `Makefile.am`: + * + * |[ + * EXTRA_DIST += \ + * tap-driver.sh \ + * tap-test + * ]| + * + * `glib-tap.mk` will be distributed implicitly due to being included in a + * `Makefile.am`. All three files should be added to version control. + * + * If you don't have access to the Autotools TAP harness, you can use the + * [gtester][gtester] and [gtester-report][gtester-report] tools, and use + * the [glib.mk](https://git.gnome.org/browse/glib/tree/glib.mk) Automake + * template provided by GLib. */ @@ -8365,18 +8441,20 @@ * and portability * * GLib defines a number of commonly used types, which can be divided - * into 4 groups: + * into several groups: * - New types which are not part of standard C (but are defined in - * various C standard library header files) - #gboolean, #gsize, - * #gssize, #goffset, #gintptr, #guintptr. + * various C standard library header files) — #gboolean, #gssize. * - Integer types which are guaranteed to be the same size across - * all platforms - #gint8, #guint8, #gint16, #guint16, #gint32, + * all platforms — #gint8, #guint8, #gint16, #guint16, #gint32, * #guint32, #gint64, #guint64. * - Types which are easier to use than their standard C counterparts - * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. * - Types which correspond exactly to standard C types, but are - * included for completeness - #gchar, #gint, #gshort, #glong, + * included for completeness — #gchar, #gint, #gshort, #glong, * #gfloat, #gdouble. + * - Types which correspond exactly to standard C99 types, but are available + * to use even if your compiler does not support C99 — #gsize, #goffset, + * #gintptr, #guintptr. * * GLib also defines macros for the limits of some of the standard * integer and floating point types, as well as macros for suitable @@ -12749,6 +12827,9 @@ * setting the `G_DEBUG` environment variable (see * [Running GLib Applications](glib-running.html)). * + * The message should typically *not* be translated to the + * user's language. + * * If g_log_default_handler() is used as the log handler function, a new-line * character will automatically be appended to @..., and need not be entered * manually. @@ -13238,6 +13319,19 @@ */ +/** + * g_date_copy: + * @date: a #GDate to copy + * + * Copies a GDate to a newly-allocated GDate. If the input was invalid + * (as determined by g_date_valid()), the invalid state will be copied + * as is into the new object. + * + * Returns: (transfer full): a newly-allocated #GDate initialized from @date + * Since: 2.56 + */ + + /** * g_date_days_between: * @date1: the first date @@ -14681,7 +14775,8 @@ * @...: format string, followed by parameters to insert * into the format string (as with printf()) * - * A convenience function/macro to log a debug message. + * A convenience function/macro to log a debug message. The message should + * typically *not* be translated to the user's language. * * If g_log_default_handler() is used as the log handler function, a new-line * character will automatically be appended to @..., and need not be entered @@ -15034,7 +15129,8 @@ * @...: format string, followed by parameters to insert * into the format string (as with printf()) * - * A convenience function/macro to log an error message. + * A convenience function/macro to log an error message. The message should + * typically *not* be translated to the user's language. * * This is not intended for end user error reporting. Use of #GError is * preferred for that instead, as it allows calling functions to perform actions @@ -15584,6 +15680,8 @@ * An implementation of the standard fprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * + * `glib/gprintf.h` must be explicitly included in order to use this function. + * * Returns: the number of bytes printed. * Since: 2.2 */ @@ -17980,8 +18078,8 @@ * same C runtime as GLib uses, which is msvcrt.dll. Note that in * current Microsoft compilers it is near impossible to convince it to * build code that would use msvcrt.dll. The last Microsoft compiler - * version that supported using msvcrt.dll as the C runtime was version - * 6. The GNU compiler and toolchain for Windows, also known as Mingw, + * version that supported using msvcrt.dll as the C runtime was version 6. + * The GNU compiler and toolchain for Windows, also known as Mingw, * fully supports msvcrt.dll. * * If you have created a #GIOChannel for a file descriptor and started @@ -23107,7 +23205,7 @@ * an absolute file name one that either begins with a directory * separator such as "\Users\tml" or begins with the root on a drive, * for example "C:\Windows". The first case also includes UNC paths - * such as "\\myserver\docs\foo". In all cases, either slashes or + * such as "\\\\myserver\docs\foo". In all cases, either slashes or * backslashes are accepted. * * Note that a file name relative to the current drive root does not @@ -23367,6 +23465,8 @@ * new-line character to the message, so typically @format should end with its * own new-line character. * + * `glib/gprintf.h` must be explicitly included in order to use this function. + * * Returns: the number of bytes printed. * Since: 2.2 */ @@ -25109,7 +25209,7 @@ * to the captured subexpression with the given name. '\0' refers * to the complete match, but '\0' followed by a number is the octal * representation of a character. To include a literal '\' in the - * replacement, write '\\'. + * replacement, write '\\\\'. * * There are also escapes that changes the case of the following text: * @@ -26726,7 +26826,7 @@ * @block_size: the number of bytes to allocate * * Allocates a block of memory from the slice allocator. - * The block adress handed out can be expected to be aligned + * The block address handed out can be expected to be aligned * to at least 1 * sizeof (void*), * though in general slices are 2 * sizeof (void*) bytes aligned, * if a malloc() fallback implementation is used instead, @@ -28419,6 +28519,8 @@ * Note that it is usually better to use g_snprintf(), to avoid the * risk of buffer overflow. * + * `glib/gprintf.h` must be explicitly included in order to use this function. + * * See also g_strdup_printf(). * * Returns: the number of bytes printed. @@ -37008,6 +37110,8 @@ * string to hold the output, instead of putting the output in a buffer * you allocate in advance. * + * `glib/gprintf.h` must be explicitly included in order to use this function. + * * Returns: the number of bytes printed. * Since: 2.4 */ @@ -37023,6 +37127,8 @@ * An implementation of the standard fprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * + * `glib/gprintf.h` must be explicitly included in order to use this function. + * * Returns: the number of bytes printed. * Since: 2.2 */ @@ -37037,6 +37143,8 @@ * An implementation of the standard vprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * + * `glib/gprintf.h` must be explicitly included in order to use this function. + * * Returns: the number of bytes printed. * Since: 2.2 */ @@ -37084,6 +37192,8 @@ * An implementation of the standard vsprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * + * `glib/gprintf.h` must be explicitly included in order to use this function. + * * Returns: the number of bytes printed. * Since: 2.2 */ @@ -37173,7 +37283,8 @@ * @...: format string, followed by parameters to insert * into the format string (as with printf()) * - * A convenience function/macro to log a warning message. + * A convenience function/macro to log a warning message. The message should + * typically *not* be translated to the user's language. * * This is not intended for end user error reporting. Use of #GError is * preferred for that instead, as it allows calling functions to perform actions diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 935fed38..4eaeb195 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -1813,7 +1813,7 @@ * Creates a new closure which invokes @callback_func with @user_data as * the last parameter. * - * Returns: a new #GCClosure + * Returns: (transfer none): a floating reference to a new #GCClosure */ @@ -1856,7 +1856,7 @@ * Creates a new closure which invokes @callback_func with @user_data as * the first parameter. * - * Returns: (transfer full): a new #GCClosure + * Returns: (transfer none): a floating reference to a new #GCClosure */ @@ -2019,7 +2019,7 @@ * } * ]| * - * Returns: (transfer full): a newly allocated #GClosure + * Returns: (transfer none): a floating reference to a new #GClosure */ @@ -5027,7 +5027,7 @@ * @struct_offset in the class structure of the interface or classed type * identified by @itype. * - * Returns: a new #GCClosure + * Returns: (transfer none): a floating reference to a new #GCClosure */ -- cgit v1.2.1