gmessages: clarify what log levels are for

For a long time we've had it as 'common knowledge' that criticals are
for programmer errors and warnings are for external errors, but we've
never documented that.  Do so.

(Modified by Philip Withnall <withnall@endlessm.com> to apply cleanly to
master; rearranged to fit in with current master documentation.)

https://bugzilla.gnome.org/show_bug.cgi?id=741049

docs/reference/glib/running.xml

@@ -122,13 +122,15 @@ How to run and debug your GLib application
       <varlistentry>
         <term>fatal-warnings</term>
         <listitem><para>Causes GLib to abort the program at the first call
-           to g_warning() or g_critical().</para>
+           to g_warning() or g_critical().  Use of this flag is not
+           recommended except when debugging.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term>fatal-criticals</term>
         <listitem><para>Causes GLib to abort the program at the first call
-           to g_critical().</para>
+           to g_critical().  This flag can be useful during debugging and
+           testing.</para>
         </listitem>
       </varlistentry>
       <varlistentry>

glib/gmessages.c

@@ -387,6 +387,16 @@ myInvalidParameterHandler(const wchar_t *expression,
  * preferred for that instead, as it allows calling functions to perform actions
  * conditional on the type of error.
  *
+ * Warning messages are intended to be used in the event of unexpected
+ * external conditions (system misconfiguration, missing files,
+ * other trusted programs violating protocol, invalid contents in
+ * trusted files, etc.)
+ *
+ * If attempting to deal with programmer errors (for example, incorrect function
+ * parameters) then you should use %G_LOG_LEVEL_CRITICAL instead.
+ *
+ * g_warn_if_reached() and g_warn_if_fail() log at %G_LOG_LEVEL_WARNING.
+ *
  * You can make warnings fatal at runtime by setting the `G_DEBUG`
  * environment variable (see
  * [Running GLib Applications](glib-running.html)):
@@ -413,13 +423,16 @@ myInvalidParameterHandler(const wchar_t *expression,
  *     into the format string (as with printf())
  *
  * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL).
- * It's more or less application-defined what constitutes
- * a critical vs. a regular warning. You could call
- * g_log_set_always_fatal() to make critical warnings exit
- * the program, then use g_critical() for fatal errors, for
- * example.
  *
- * You can also make critical warnings fatal at runtime by
+ * Critical warnings are intended to be used in the event of an error
+ * that originated in the current process (a programmer error).
+ * Logging of a critical error is by definition an indication of a bug
+ * somewhere in the current program (or its libraries).
+ *
+ * g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
+ * g_return_val_if_reached() log at %G_LOG_LEVEL_CRITICAL.
+ *
+ * You can make critical warnings fatal at runtime by
  * setting the `G_DEBUG` environment variable (see
  * [Running GLib Applications](glib-running.html)):
  *
@@ -427,6 +440,8 @@ myInvalidParameterHandler(const wchar_t *expression,
  *   G_DEBUG=fatal-warnings gdb ./my-program
  * ]|
  *
+ * You can also use g_log_set_always_fatal().
+ *
  * Any unrelated failures can be skipped over in
  * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
  *
@@ -778,6 +793,11 @@ g_log_set_always_fatal (GLogLevelFlags fatal_mask)
  * g_log_set_writer_func(). See
  * [Using Structured Logging][using-structured-logging].
  *
+ * This function is mostly intended to be used with
+ * %G_LOG_LEVEL_CRITICAL.  You should typically not set
+ * %G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or
+ * %G_LOG_LEVEL_DEBUG as fatal except inside of test programs.
+ *
  * Returns: the old fatal mask for the log domain
  */
 GLogLevelFlags