diff options
author | Florian Müllner <fmuellner@gnome.org> | 2018-12-02 23:45:26 +0100 |
---|---|---|
committer | Florian Müllner <fmuellner@gnome.org> | 2018-12-02 23:45:40 +0100 |
commit | 33e0995a28a9b83522578e701147224bf04d9630 (patch) | |
tree | 8209380041d57905ac597c4d50775e3757ccad64 /gir/glib-2.0.c | |
parent | 925c3b875861e83d3d6808439b61e80fe5ee8b48 (diff) | |
download | gobject-introspection-33e0995a28a9b83522578e701147224bf04d9630.tar.gz |
gir: Update annotations from glib git master
Diffstat (limited to 'gir/glib-2.0.c')
-rw-r--r-- | gir/glib-2.0.c | 84 |
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. */ |