[glib: 1/2] gunicollate: Document that g_utf8_collate() can’t compare everything

[Sebastian Dröge <sdroege src gnome org>]

commit 5483816bac463780848c49c52c565094a02c14ac
Author: Philip Withnall <pwithnall endlessos org>
Date:   Wed Jan 19 12:38:37 2022 +0000

    gunicollate: Document that g_utf8_collate() can’t compare everything
    
    There is not a total collation order defined over all Unicode
    codepoints, so sometimes `g_utf8_collate()` can’t return a useful
    result. Document that.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Fixes: #517

 glib/gunicollate.c | 4 ++++
 1 file changed, 4 insertions(+)
---
diff --git a/glib/gunicollate.c b/glib/gunicollate.c
index dfed1041d..6b6c559e8 100644
--- a/glib/gunicollate.c
+++ b/glib/gunicollate.c
@@ -71,6 +71,10 @@ msc_strxfrm_wrapper (char       *string1,
  * compare the keys with strcmp() when sorting instead of sorting 
  * the original strings.
  * 
+ * If the two strings are not comparable due to being in different collation
+ * sequences, the result is undefined. This can happen if the strings are in
+ * different language scripts, for example.
+ *
  * Returns: < 0 if @str1 compares before @str2, 
  *   0 if they compare equal, > 0 if @str1 compares after @str2.
  **/