[glib: 1/16] docs: Add missing documentation for warnings and assertions

[Emmanuele Bassi <ebassi src gnome org>]

commit 1a46bf88bb776b6a9c211f9abb695ac4d8bf03d0
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Nov 23 12:19:19 2018 +0000

    docs: Add missing documentation for warnings and assertions
    
    These symbols were listed in glib-undocumented.txt. Thanks gtk-doc.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 glib/docs.c       | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 glib/gmessages.c  | 22 ++++++++++++++--------
 glib/gtestutils.c | 13 ++++++++-----
 3 files changed, 70 insertions(+), 13 deletions(-)
---
diff --git a/glib/docs.c b/glib/docs.c
index 562fef0aa..f45a1fee8 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -2835,6 +2835,54 @@
  * 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(), 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.
+ */
+
 /* Windows Compatibility Functions {{{1 */
 
 /**
diff --git a/glib/gmessages.c b/glib/gmessages.c
index a43ff0e58..0210b7a8e 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -2752,9 +2752,12 @@ _g_log_writer_fallback (GLogLevelFlags   log_level,
 
 /**
  * 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.
  */
 void
 g_return_if_fail_warning (const char *log_domain,
@@ -2770,11 +2773,14 @@ g_return_if_fail_warning (const char *log_domain,
 
 /**
  * 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.
  */
 void
 g_warn_message (const char     *domain,
diff --git a/glib/gtestutils.c b/glib/gtestutils.c
index ac85f4b2b..874d5dc06 100644
--- a/glib/gtestutils.c
+++ b/glib/gtestutils.c
@@ -2623,11 +2623,14 @@ g_assertion_message (const char     *domain,
 
 /**
  * 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.
  */
 void
 g_assertion_message_expr (const char     *domain,