[glib/gerror-utf8-docs] gerror: Clarify docs around message requirements

[Matthias Clasen <matthiasc src gnome org>]

commit 63fa4e7d348d9f47ce2fb5ac69431272f91d5280
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Apr 14 14:55:23 2021 -0400

    gerror: Clarify docs around message requirements
    
    Make it clear that error->message is a user-visible string
    that must be in UTF-8, and point out helpers for that.

 glib/gerror.c | 6 ++++++
 1 file changed, 6 insertions(+)
---
diff --git a/glib/gerror.c b/glib/gerror.c
index 82bf626ed..222db1cc2 100644
--- a/glib/gerror.c
+++ b/glib/gerror.c
@@ -114,6 +114,12 @@
  * function (the file being opened, or whatever - though in the
  * g_file_get_contents() case, the @message already contains a filename).
  *
+ * Since error messages may be displayed to the user, they need to be valid
+ * UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in
+ * particular when formatting error messages with filenames, which are in
+ * the 'filename encoding', and need to be turned into UTF-8 using
+ * g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid().
+ *
  * Note, however, that many error messages are too technical to display to the
  * user in an application, so prefer to use g_error_matches() to categorize errors
  * from called functions, and build an appropriate error message for the context