diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2016-08-11 16:36:52 +0200 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2016-08-11 16:36:52 +0200 |
commit | a816e723ea4bfdacc36b1abd65c180f399964079 (patch) | |
tree | d2ad8593f91edce4fc9599d44ed1711672077567 /gir | |
parent | 86c6ff075752a8e6d3fb4d2a85f19bf46a77a349 (diff) | |
download | gobject-introspection-a816e723ea4bfdacc36b1abd65c180f399964079.tar.gz |
gir: Update annotations from GLib git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 48 | ||||
-rw-r--r-- | gir/glib-2.0.c | 99 |
2 files changed, 132 insertions, 15 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 4ada3241..201ed2d7 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -5592,12 +5592,13 @@ * instance, on Windows a socket is always seen as writable until a write * returns %G_IO_ERROR_WOULD_BLOCK. * - * As with #GSocket, #GDatagramBaseds can be either connection oriented or - * connectionless. The interface does not cover connection establishment — use - * methods on the underlying type to establish a connection before sending and - * receiving data through the #GDatagramBased API. For connectionless socket - * types the target/source address is specified or received in each I/O - * operation. + * As with #GSocket, #GDatagramBaseds can be either connection oriented (for + * example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be + * datagram-based, not stream-based. The interface does not cover connection + * establishment — use methods on the underlying type to establish a connection + * before sending and receiving data through the #GDatagramBased API. For + * connectionless socket types the target/source address is specified or + * received in each I/O operation. * * Like most other APIs in GLib, #GDatagramBased is not inherently thread safe. * To use a #GDatagramBased concurrently from multiple threads, you must @@ -12589,8 +12590,8 @@ /** * g_app_info_launch_default_for_uri: * @uri: the uri to show - * @launch_context: (allow-none): an optional #GAppLaunchContext. - * @error: a #GError. + * @launch_context: (allow-none): an optional #GAppLaunchContext + * @error: (nullable): return location for an error, or %NULL * * Utility function that launches the default application * registered to handle the specified uri. Synchronous I/O @@ -12602,6 +12603,37 @@ /** + * g_app_info_launch_default_for_uri_async: + * @uri: the uri to show + * @context: (allow-none): an optional #GAppLaunchContext + * cancellable: (allow-none): a #GCancellable + * @callback: (allow-none): a #GASyncReadyCallback to call when the request is done + * @user_data: (allow-none): data to pass to @callback + * + * Async version of g_app_info_launch_default_for_uri(). + * + * This version is useful if you are interested in receiving + * error information in the case where the application is + * sandboxed and the portal may present an application chooser + * dialog to the user. + * + * Since: 2.50 + */ + + +/** + * g_app_info_launch_default_for_uri_finish: + * @result: a #GAsyncResult + * @error: (nullable): return location for an error, or %NULL + * + * Finishes an asynchronous launch-default-for-uri operation. + * + * Returns: %TRUE if the launch was successful, %FALSE if @error is set + * Since: 2.50 + */ + + +/** * g_app_info_launch_uris: * @appinfo: a #GAppInfo * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch. diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index cb1bb41e..652521c5 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -8255,6 +8255,15 @@ * rather than as a single string containing all the information in an arbitrary * format. * + * The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error() + * will use the traditional g_log() API unless you define the symbol + * `G_LOG_USE_STRUCTURED` before including `glib.h`. But note that even messages + * logged through the traditional g_log() API are ultimatively passed to + * g_log_structured(), so that all log messages end up in same destination. + * If `G_LOG_USE_STRUCTURED` is defined, g_test_expect_message() will become + * will become ineffective for the wrapper macros g_warning() and friends (see + * [Testing for Messages][testing-for-messages]). + * * The support for structured logging was motivated by the following needs (some * of which were supported previously; others weren’t): * * Support for multiple logging levels. @@ -8289,6 +8298,66 @@ * zero-length #GLogField to g_log_structured_array(). * * Color output needed to be supported on the terminal, to make reading * through logs easier. + * + * ## Log Domains + * + * Log domains may be used to broadly split up the origins of log messages. + * Typically, there are one or a few log domains per application or library. + * %G_LOG_DOMAIN should be used to define the default log domain for the current + * compilation unit — it is typically defined at the top of a source file, or in + * the preprocessor flags for a group of source files. + * + * 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`. + * + * ## Debug Message Output + * + * The default log functions (g_log_default_handler() for the old-style API and + * g_log_writer_default() for the structured API) both drop debug and + * informational messages by default, unless the log domains of those messages + * are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to + * `all`). + * + * It is recommended that custom log writer functions re-use the + * `G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one, + * so that developers can re-use the same debugging techniques and tools across + * projects. + * + * ## Testing for Messages + * + * With the old g_log() API, g_test_expect_message() and + * g_test_assert_expected_messages() could be used in simple cases to check + * whether some code under test had emitted a given log message. These + * functions have been deprecated with the structured logging API, for several + * reasons: + * * They relied on an internal queue which was too inflexible for many use + * cases, where messages might be emitted in several orders, some + * messages might not be emitted deterministically, or messages might be + * emitted by unrelated log domains. + * * They do not support structured log fields. + * * Examining the log output of code is a bad approach to testing it, and + * while it might be necessary for legacy code which uses g_log(), it should + * be avoided for new code using g_log_structured(). + * + * They will continue to work as before if g_log() is in use (and + * %G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the + * structured logging API. + * + * Examining the log output of code is discouraged: libraries should not emit to + * `stderr` during defined behaviour, and hence this should not be tested. If + * the log emissions of a library during undefined behaviour need to be tested, + * they should be limited to asserting that the library aborts and prints a + * suitable error message before aborting. This should be done with + * g_test_trap_assert_stderr(). + * + * If it is really necessary to test the structured log messages emitted by a + * particular piece of code – and the code cannot be restructured to be more + * suitable to more conventional unit testing – you should write a custom log + * writer function (see g_log_set_writer_func()) which appends all log messages + * to a queue. When you want to check the log messages, examine and clear the + * queue, ignoring irrelevant log messages (for example, from log domains other + * than the one under test). */ @@ -14384,8 +14453,9 @@ * character will automatically be appended to @..., and need not be entered * manually. * - * Such messages are suppressed by the g_log_default_handler() unless - * the G_MESSAGES_DEBUG environment variable is set appropriately. + * Such messages are suppressed by the g_log_default_handler() and + * g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is + * set appropriately. * * Since: 2.6 */ @@ -17013,8 +17083,9 @@ * character will automatically be appended to @..., and need not be entered * manually. * - * Such messages are suppressed by the g_log_default_handler() unless - * the G_MESSAGES_DEBUG environment variable is set appropriately. + * Such messages are suppressed by the g_log_default_handler() and + * g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is + * set appropriately. * * Since: 2.40 */ @@ -19488,8 +19559,10 @@ * g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); * ]| * - * Note also that, even if no structured fields are specified, the key-value - * part of the argument list must be %NULL-terminated. + * Note also that, even if no other structured fields are specified, there + * must always be a "MESSAGE" key before the format string. The "MESSAGE"-format + * pair has to be the last of the key-value pairs, and "MESSAGE" is the only + * field for which printf()-style formatting is supported. * * The default writer function for `stdout` and `stderr` will automatically * append a new-line character after the message, so you should not add one @@ -19542,6 +19615,10 @@ * This is suitable for use as a #GLogWriterFunc, and is the default writer used * if no other is set using g_log_set_writer_func(). * + * As with g_log_default_handler(), this function drops debug and informational + * messages unless their log domain (or `all`) is listed in the space-separated + * `G_MESSAGES_DEBUG` environment variable. + * * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise * Since: 2.50 */ @@ -29463,6 +29540,10 @@ * Asserts that all messages previously indicated via * g_test_expect_message() have been seen and suppressed. * + * This API may only be used with the old logging API (g_log() without + * %G_LOG_USE_STRUCTURED defined). It will not work with the structured logging + * API. See [Testing for Messages][testing-for-messages]. + * * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly * expected via g_test_expect_message() then they will be ignored. * @@ -29588,6 +29669,10 @@ * message is logged, it will not be printed, and the test case will * not abort. * + * This API may only be used with the old logging API (g_log() without + * %G_LOG_USE_STRUCTURED defined). It will not work with the structured logging + * API. See [Testing for Messages][testing-for-messages]. + * * Use g_test_assert_expected_messages() to assert that all * previously-expected messages have been seen and suppressed. * @@ -29759,7 +29844,7 @@ * `quick`: Quick tests, should run really quickly and give good coverage. * * `undefined`: Tests for undefined behaviour, may provoke programming errors - * under g_test_trap_subprocess() or g_test_expect_messages() to check + * under g_test_trap_subprocess() or g_test_expect_message() to check * that appropriate assertions or warnings are given * * `no-undefined`: Avoid tests for undefined behaviour |