gir: Update annotations from GLib git master

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].
  */