gir: Update annotations from glib git master

1 files changed, 70 insertions, 14 deletions

diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 8a8ce87a..43fc6ef7 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -9064,6 +9064,53 @@
 
 
 /**
+ * SECTION:warnings
+ * @title: Warnings and Assertions
+ * @short_description: warnings and assertions to use in runtime code
+ *
+ * GLib defines several warning functions and assertions which can be used to
+ * warn of programmer errors when calling functions, and print error messages
+ * from command line programs.
+ *
+ * The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
+ * g_return_val_if_reached() macros are intended as pre-condition assertions, to
+ * be used at the top of a public function to check that the function’s
+ * arguments are acceptable. Any failure of such a pre-condition assertion is
+ * considered a programming error on the part of the caller of the public API,
+ * and the program is considered to be in an undefined state afterwards. They
+ * are similar to the libc assert() function, but provide more context on
+ * failures.
+ *
+ * For example:
+ * |[<!-- language="C" -->
+ * gboolean
+ * g_dtls_connection_shutdown (GDtlsConnection  *conn,
+ *                             gboolean          shutdown_read,
+ *                             gboolean          shutdown_write,
+ *                             GCancellable     *cancellable,
+ *                             GError          **error)
+ * {
+ *   // local variable declarations
+ *
+ *   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
+ *   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
+ *   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
+ *
+ *   // function body
+ *
+ *   return return_val;
+ * }
+ * ]|
+ *
+ * g_print(), g_printerr() and g_set_print_handler() are intended to be used for
+ * output from command line applications, since they output to standard output
+ * and standard error by default — whereas functions like g_message() and
+ * g_log() may be redirected to special purpose message windows, files, or the
+ * system journal.
+ */
+
+
+/**
  * SECTION:windows
  * @title: Windows Compatibility Functions
  * @short_description: UNIX emulation on Windows
@@ -10281,11 +10328,14 @@
 
 /**
  * g_assertion_message_expr: (skip)
- * @domain: (nullable):
- * @file:
- * @line:
- * @func:
- * @expr: (nullable):
+ * @domain: (nullable): log domain
+ * @file: file containing the assertion
+ * @line: line number of the assertion
+ * @func: function containing the assertion
+ * @expr: (nullable): expression which failed
+ *
+ * Internal function used to print messages from the public g_assert() and
+ * g_assert_not_reached() macros.
  */
 
 
@@ -11224,7 +11274,7 @@
  * g_atomic_ref_count_init:
  * @arc: the address of an atomic reference count variable
  *
- * Atomically initializes a reference count variable.
+ * Initializes a reference count variable.
  *
  * Since: 2.58
  */
@@ -26947,9 +26997,12 @@
 
 /**
  * g_return_if_fail_warning: (skip)
- * @log_domain: (nullable):
- * @pretty_function:
- * @expression: (nullable):
+ * @log_domain: (nullable): log domain
+ * @pretty_function: function containing the assertion
+ * @expression: (nullable): expression which failed
+ *
+ * Internal function used to print messages from the public g_return_if_fail()
+ * and g_return_val_if_fail() macros.
  */
 
 
@@ -38906,11 +38959,14 @@
 
 /**
  * g_warn_message: (skip)
- * @domain: (nullable):
- * @file:
- * @line:
- * @func:
- * @warnexpr: (nullable):
+ * @domain: (nullable): log domain
+ * @file: file containing the warning
+ * @line: line number of the warning
+ * @func: function containing the warning
+ * @warnexpr: (nullable): expression which failed
+ *
+ * Internal function used to print messages from the public g_warn_if_reached()
+ * and g_warn_if_fail() macros.
  */