Created attachment 292031 [details] [review]
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.

Review of attachment 292031 [details] [review]:

::: docs/reference/glib/running.xml
@@ +124,3 @@
         <listitem><para>Causes GLib to abort the program at the first call
+           to g_warning() or g_critical().  Use of this flag is not
+           recommended.</para>

‘except when debugging’?

::: glib/gmessages.c
@@ +213,3 @@
+ * Critical errors can be fatal (ie: result in termination of the
+ * program) if the `G_DEBUG` environment variable is set accordingly.
+ * See [Running GLib Applications](glib-running.html).  You can also use

Is that xref correct? docs/reference/glib/running.html gives the <refentry id> as simply ’glib-running’.

(In reply to Philip Withnall from comment #2)
> Review of attachment 292031 [details] [review] [review]:
> 
> ::: docs/reference/glib/running.xml
> @@ +124,3 @@
>          <listitem><para>Causes GLib to abort the program at the first call
> +           to g_warning() or g_critical().  Use of this flag is not
> +           recommended.</para>
> 
> ‘except when debugging’?

I’ve made this change locally.

> ::: glib/gmessages.c
> @@ +213,3 @@
> + * Critical errors can be fatal (ie: result in termination of the
> + * program) if the `G_DEBUG` environment variable is set accordingly.
> + * See [Running GLib Applications](glib-running.html).  You can also use
> 
> Is that xref correct? docs/reference/glib/running.html gives the <refentry
> id> as simply ’glib-running’.

It is the correct xref. Not changing it.

Comment on attachment 292031 [details] [review]
gmessages: clarify what log levels are for

Rebased on master, rearranged a bit to fit with the current docs, fixed my first review comment from above, ignored the second, and pushed.

Attachment 292031 [details] pushed as ad3b2f2 - gmessages: clarify what log levels are for