diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2016-08-26 19:02:22 +0200 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2016-08-26 19:02:22 +0200 |
commit | ee9d4cdfdcc17da3de2229913ab98abaca8eddf3 (patch) | |
tree | d42decfc7c2a1ef4fba0099b351e564aaa7d7a8c /gir | |
parent | 40a5e5df2dd75f40b850a95c715b66dc85cc9506 (diff) | |
download | gobject-introspection-ee9d4cdfdcc17da3de2229913ab98abaca8eddf3.tar.gz |
gir: Update annotations from GLib git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 2 | ||||
-rw-r--r-- | gir/glib-2.0.c | 350 |
2 files changed, 206 insertions, 146 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 201ed2d7..c4eedd07 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -26681,7 +26681,7 @@ * Creates a new #GInetSocketAddress for @address and @port. * * If @address is an IPv6 address, it can also contain a scope ID - * (separated from the address by a "<literal>%</literal>"). + * (separated from the address by a `%`). * * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be * parsed. diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 652521c5..9aa2e6fe 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -1227,6 +1227,9 @@ * custom log handler functions behave similarly, so that logging calls in user * code do not need modifying to add a new-line character to the message if the * log handler is changed. + * + * This is not used if structured logging is enabled; see + * [Using Structured Logging][using-structured-logging]. */ @@ -4191,6 +4194,9 @@ * G_LOG_FATAL_MASK: * * GLib log levels that are considered fatal by default. + * + * This is not used if structured logging is enabled; see + * [Using Structured Logging][using-structured-logging]. */ @@ -7235,15 +7241,141 @@ /** * SECTION:messages - * @title: Message Logging - * @short_description: versatile support for logging messages - * with different levels of importance + * @Title: Message Output and Debugging Functions + * @Short_description: functions to output messages and help debug applications + * + * These functions provide support for outputting messages. + * + * The g_return family of macros (g_return_if_fail(), + * g_return_val_if_fail(), g_return_if_reached(), + * g_return_val_if_reached()) should only be used for programming + * errors, a typical use case is checking for invalid parameters at + * the beginning of a public function. They should not be used if + * you just mean "if (error) return", they should only be used if + * you mean "if (bug in program) return". The program behavior is + * generally considered undefined after one of these checks fails. + * They are not intended for normal control flow, only to give a + * perhaps-helpful warning before giving up. + * + * Structured logging output is supported using g_log_structured(). This differs + * from the traditional g_log() API in that log messages are handled as a + * collection of key–value pairs representing individual pieces of information, + * 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 + * 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. + * * Structured log support with the ability to add `MESSAGE_ID`s (see + * g_log_structured()). + * * Moving the responsibility for filtering log messages from the program to + * the log viewer — instead of libraries and programs installing log handlers + * (with g_log_set_handler()) which filter messages before output, all log + * messages are outputted, and the log viewer program (such as `journalctl`) + * must filter them. This is based on the idea that bugs are sometimes hard + * to reproduce, so it is better to log everything possible and then use + * tools to analyse the logs than it is to not be able to reproduce a bug to + * get additional log data. Code which uses logging in performance-critical + * sections should compile out the g_log_structured() calls in + * release builds, and compile them in in debugging builds. + * * A single writer function which handles all log messages in a process, from + * all libraries and program code; rather than multiple log handlers with + * poorly defined interactions between them. This allows a program to easily + * change its logging policy by changing the writer function, for example to + * log to an additional location or to change what logging output fallbacks + * are used. The log writer functions provided by GLib are exposed publicly + * so they can be used from programs’ log writers. This allows log writer + * policy and implementation to be kept separate. + * * If a library wants to add standard information to all of its log messages + * (such as library state) or to redact private data (such as passwords or + * network credentials), it should use a wrapper function around its + * g_log_structured() calls or implement that in the single log writer + * function. + * * If a program wants to pass context data from a g_log_structured() call to + * its log writer function so that, for example, it can use the correct + * server connection to submit logs to, that user data can be passed as a + * zero-length #GLogField to g_log_structured_array(). + * * Color output needed to be supported on the terminal, to make reading + * through logs easier. * - * These functions provide support for logging error messages - * or messages used for debugging. + * ## Using Structured Logging + * + * To use structured logging (rather than the old-style logging), either use + * the g_log_structured() and g_log_structured_array() functions; or define + * `G_LOG_USE_STRUCTURED` before including any GLib header, and use the + * g_message(), g_debug(), g_error() (etc.) macros. + * + * You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(), + * but it is a good idea to avoid confusion. + * + * ## Log Domains * - * There are several built-in levels of messages, defined in - * #GLogLevelFlags. These can be extended with user-defined levels. + * 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). */ @@ -8232,136 +8364,6 @@ /** - * SECTION:warnings - * @Title: Message Output and Debugging Functions - * @Short_description: functions to output messages and help debug applications - * - * These functions provide support for outputting messages. - * - * The g_return family of macros (g_return_if_fail(), - * g_return_val_if_fail(), g_return_if_reached(), - * g_return_val_if_reached()) should only be used for programming - * errors, a typical use case is checking for invalid parameters at - * the beginning of a public function. They should not be used if - * you just mean "if (error) return", they should only be used if - * you mean "if (bug in program) return". The program behavior is - * generally considered undefined after one of these checks fails. - * They are not intended for normal control flow, only to give a - * perhaps-helpful warning before giving up. - * - * Structured logging output is supported using g_log_structured(). This differs - * from the traditional g_log() API in that log messages are handled as a - * collection of key–value pairs representing individual pieces of information, - * 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. - * * Structured log support with the ability to add `MESSAGE_ID`s (see - * g_log_structured()). - * * Moving the responsibility for filtering log messages from the program to - * the log viewer — instead of libraries and programs installing log handlers - * (with g_log_set_handler()) which filter messages before output, all log - * messages are outputted, and the log viewer program (such as `journalctl`) - * must filter them. This is based on the idea that bugs are sometimes hard - * to reproduce, so it is better to log everything possible and then use - * tools to analyse the logs than it is to not be able to reproduce a bug to - * get additional log data. Code which uses logging in performance-critical - * sections should compile out the g_log_structured() calls in - * release builds, and compile them in in debugging builds. - * * A single writer function which handles all log messages in a process, from - * all libraries and program code; rather than multiple log handlers with - * poorly defined interactions between them. This allows a program to easily - * change its logging policy by changing the writer function, for example to - * log to an additional location or to change what logging output fallbacks - * are used. The log writer functions provided by GLib are exposed publicly - * so they can be used from programs’ log writers. This allows log writer - * policy and implementation to be kept separate. - * * If a library wants to add standard information to all of its log messages - * (such as library state) or to redact private data (such as passwords or - * network credentials), it should use a wrapper function around its - * g_log_structured() calls or implement that in the single log writer - * function. - * * If a program wants to pass context data from a g_log_structured() call to - * its log writer function so that, for example, it can use the correct - * server connection to submit logs to, that user data can be passed as a - * 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). - */ - - -/** * SECTION:windows * @title: Windows Compatibility Functions * @short_description: UNIX emulation on Windows @@ -10303,7 +10305,14 @@ * * membuf = g_malloc (8192); * - * /* Some computation on membuf + * /<!-- -->* Some computation on membuf *<!-- -->/ + * + * /<!-- -->* membuf will be automatically freed here *<!-- -->/ + * return TRUE; + * } + * ]| + * + * Since: 2.44 */ @@ -12573,6 +12582,10 @@ * 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. + * + * If structured logging is enabled, this will use g_log_structured(); + * otherwise it will use g_log(). See + * [Using Structured Logging][using-structured-logging]. */ @@ -14457,6 +14470,10 @@ * g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is * set appropriately. * + * If structured logging is enabled, this will use g_log_structured(); + * otherwise it will use g_log(). See + * [Using Structured Logging][using-structured-logging]. + * * Since: 2.6 */ @@ -14811,6 +14828,10 @@ * 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. + * + * If structured logging is enabled, this will use g_log_structured(); + * otherwise it will use g_log(). See + * [Using Structured Logging][using-structured-logging]. */ @@ -17087,6 +17108,10 @@ * g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is * set appropriately. * + * If structured logging is enabled, this will use g_log_structured(); + * otherwise it will use g_log(). See + * [Using Structured Logging][using-structured-logging]. + * * Since: 2.40 */ @@ -19296,6 +19321,9 @@ * 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. + * + * If [structured logging is enabled][using-structured-logging] this will + * output via the structured log writer function (see g_log_set_writer_func()). */ @@ -19329,6 +19357,9 @@ * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for * the rest. + * + * This has no effect if structured logging is enabled; see + * [Using Structured Logging][using-structured-logging]. */ @@ -19339,6 +19370,9 @@ * in g_log_set_handler() * * Removes the log handler. + * + * This has no effect if structured logging is enabled; see + * [Using Structured Logging][using-structured-logging]. */ @@ -19362,7 +19396,7 @@ * Structured log messages (using g_log_structured() and * g_log_structured_array()) are fatal only if the default log writer is used; * otherwise it is up to the writer function to determine which log messages - * are fatal. + * are fatal. See [Using Structured Logging][using-structured-logging]. * * Returns: the old fatal mask */ @@ -19378,6 +19412,9 @@ * and log level combination. By default, GLib uses * g_log_default_handler() as default log handler. * + * This has no effect if structured logging is enabled; see + * [Using Structured Logging][using-structured-logging]. + * * Returns: the previous default log handler * Since: 2.6 */ @@ -19394,7 +19431,8 @@ * This has no effect on structured log messages (using g_log_structured() or * g_log_structured_array()). To change the fatal behaviour for specific log * messages, programs must install a custom log writer function using - * g_log_set_writer_func(). + * g_log_set_writer_func(). See + * [Using Structured Logging][using-structured-logging]. * * Returns: the old fatal mask for the log domain */ @@ -19420,6 +19458,9 @@ * you want to set a handler for this log level you must combine it with * #G_LOG_FLAG_FATAL. * + * This has no effect if structured logging is enabled; see + * [Using Structured Logging][using-structured-logging]. + * * Here is an example for adding a log handler for all warning messages * in the default domain: * |[<!-- language="C" --> @@ -19457,6 +19498,9 @@ * * Like g_log_sets_handler(), but takes a destroy notify for the @user_data. * + * This has no effect if structured logging is enabled; see + * [Using Structured Logging][using-structured-logging]. + * * Returns: the id of the new handler * Since: 2.46 */ @@ -19743,6 +19787,9 @@ * 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. + * + * If [structured logging is enabled][using-structured-logging] this will + * output via the structured log writer function (see g_log_set_writer_func()). */ @@ -21433,6 +21480,10 @@ * 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. + * + * If structured logging is enabled, this will use g_log_structured(); + * otherwise it will use g_log(). See + * [Using Structured Logging][using-structured-logging]. */ @@ -22993,8 +23044,8 @@ * g_print() should not be used from within libraries for debugging * messages, since it may be redirected by applications to special * purpose message windows or even files. Instead, libraries should - * use g_log(), or the convenience functions g_message(), g_warning() - * and g_error(). + * use g_log(), g_log_structured(), or the convenience macros g_message(), + * g_warning() and g_error(). */ @@ -23009,8 +23060,8 @@ * new-line character. * * g_printerr() should not be used from within libraries. - * Instead g_log() should be used, or the convenience functions - * g_message(), g_warning() and g_error(). + * Instead g_log() or g_log_structured() should be used, or the convenience + * macros g_message(), g_warning() and g_error(). */ @@ -24372,6 +24423,10 @@ * * Returns the compile options that @regex was created with. * + * Depending on the version of PCRE that is used, this may or may not + * include flags set by option expressions such as `(?i)` found at the + * top-level within the compiled pattern. + * * Returns: flags from #GRegexCompileFlags * Since: 2.26 */ @@ -29924,7 +29979,8 @@ * This handler also has no effect on structured log messages (using * g_log_structured() or g_log_structured_array()). To change the fatal * behaviour for specific log messages, programs must install a custom log - * writer function using g_log_set_writer_func(). + * writer function using g_log_set_writer_func().See + * [Using Structured Logging][using-structured-logging]. * * Since: 2.22 */ @@ -36667,6 +36723,10 @@ * If g_log_default_handler() is used as the log handler function, * a newline character will automatically be appended to @..., and * need not be entered manually. + * + * If structured logging is enabled, this will use g_log_structured(); + * otherwise it will use g_log(). See + * [Using Structured Logging][using-structured-logging]. */ |