From 3532e3ca1c0e7d6add165f950b31638ba16ff4ee Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 23 Nov 2023 14:02:04 +0000 Subject: [PATCH] docs: Move the warnings SECTION Move it to a separate file. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/glib/glib.toml.in | 1 + docs/reference/glib/meson.build | 1 + docs/reference/glib/warnings.md | 73 ++++++++++++++++++++++++++++++++ glib/docs.c | 55 ------------------------ 4 files changed, 75 insertions(+), 55 deletions(-) create mode 100644 docs/reference/glib/warnings.md diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 0efe8fddc..d720be5cd 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -61,6 +61,7 @@ content_files = [ "memory-slices.md", "error-reporting.md", "logging.md", + "warnings.md", "file-utils.md", "host-utils.md", "misc-utils.md", diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index a02f055b1..438b4ae9a 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -181,6 +181,7 @@ expand_content_files = [ 'unix.md', 'uuid.md', 'version.md', + 'warnings.md', ] glib_toml = configure_file(input: 'glib.toml.in', output: 'glib.toml', configuration: toml_conf) diff --git a/docs/reference/glib/warnings.md b/docs/reference/glib/warnings.md new file mode 100644 index 000000000..bb05656c7 --- /dev/null +++ b/docs/reference/glib/warnings.md @@ -0,0 +1,73 @@ +Title: Warnings and Assertions +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 2018 Endless Mobile, Inc. +SPDX-FileCopyrightText: 2023 Daniel Carpenter + +# Warnings and Assertions + +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. + +## Pre-condition Assertions + +The [func@GLib.return_if_fail], [func@GLib.return_val_if_fail], +[func@GLib.return_if_reached] and [func@GLib.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()`](man:assert(3)) +function, but provide more context on failures. + +For example: +```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; +} +``` + +[func@GLib.warn_if_fail] and [func@GLib.warn_if_reached] behave similarly, but +they will not abort the program on failure. The program should be considered to +be in an undefined state if they fail, however. + +## Messages + +[func@GLib.print] and [func@GLib.printerr] 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 [func@GLib.message] and +[func@GLib.log] may be redirected to special purpose message windows, files, or +the system journal. + +The default print handlers may be overridden with [func@GLib.set_print_handler] +and [func@GLib.set_printerr_handler]. + +### Encoding + +If the console encoding is not UTF-8 (as specified by +[func@GLib.get_console_charset]) then these functions convert the message first. +Any Unicode characters not defined by that charset are replaced by `'?'`. On +Linux, [`setlocale()`](man:setlocale(3)) must be called early in `main()` to +load the encoding. This behaviour can be changed by providing custom handlers to +[func@GLib.set_print_handler], [func@GLib.set_printerr_handler] and +[func@GLib.log_set_handler]. + +## Debugging Utilities + + * [func@GLib.on_error_query] + * [func@GLib.on_error_stack_trace] + * [func@GLib.BREAKPOINT] diff --git a/glib/docs.c b/glib/docs.c index af10f6c6a..b2ea2685f 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -2860,61 +2860,6 @@ * Since: 2.44 */ -/* Warnings and Assertions {{{1 */ - -/** - * 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: - * |[ - * 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() and g_printerr() 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. - * - * If the console encoding is not UTF-8 (as specified by g_get_console_charset()) - * then these functions convert the message first. Any Unicode - * characters not defined by that charset are replaced by `'?'`. On Linux, - * setlocale() must be called early in main() to load the encoding. This behaviour - * can be changed by providing custom handlers to g_set_print_handler(), - * g_set_printerr_handler() and g_log_set_handler(). - */ - /* Windows Compatibility Functions {{{1 */ /**