docs: Move the warnings SECTION

Move it to a separate file.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037

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",

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)

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]

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:
- * |[<!-- 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() 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 */
 
 /**