From d2b419c81f91353682bcba4263756a5d572c8f39 Mon Sep 17 00:00:00 2001
From: Philip Withnall <withnall@endlessm.com>
Date: Fri, 17 May 2019 13:03:27 +0100
Subject: [PATCH] gsettings: Document that lists are returned in no defined
 order

The caller cannot assume that the lists returned by various GSettings
functions (for example, lists of keys or schemas) will be returned in
any particular order.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Helps: #1781
---
 gio/gsettings.c       |  6 ++++--
 gio/gsettingsschema.c | 17 +++++++++--------
 2 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/gio/gsettings.c b/gio/gsettings.c
index dd8f94485..f36ff26b2 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -2459,7 +2459,8 @@ g_settings_get_child (GSettings   *settings,
  * You should free the return value with g_strfreev() when you are done
  * with it.
  *
- * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
+ * Returns: (transfer full) (element-type utf8): a list of the keys on
+ *    @settings, in no defined order
  */
 gchar **
 g_settings_list_keys (GSettings *settings)
@@ -2483,7 +2484,8 @@ g_settings_list_keys (GSettings *settings)
  * You should free the return value with g_strfreev() when you are done
  * with it.
  *
- * Returns: (transfer full) (element-type utf8): a list of the children on @settings
+ * Returns: (transfer full) (element-type utf8): a list of the children on
+ *    @settings, in no defined order
  */
 gchar **
 g_settings_list_children (GSettings *settings)
diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c
index f7c50c210..3a60b8c64 100644
--- a/gio/gsettingsschema.c
+++ b/gio/gsettingsschema.c
@@ -742,9 +742,9 @@ g_settings_schema_source_get_text_tables (GSettingsSchemaSource *source)
  * @source: a #GSettingsSchemaSource
  * @recursive: if we should recurse
  * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the
- *   list of non-relocatable schemas
+ *   list of non-relocatable schemas, in no defined order
  * @relocatable: (out) (transfer full) (array zero-terminated=1): the list
- *   of relocatable schemas
+ *   of relocatable schemas, in no defined order
  *
  * Lists the schemas in a given source.
  *
@@ -857,8 +857,8 @@ ensure_schema_lists (void)
  * Deprecated.
  *
  * Returns: (element-type utf8) (transfer none):  a list of #GSettings
- *   schemas that are available.  The list must not be modified or
- *   freed.
+ *   schemas that are available, in no defined order.  The list must not be
+ *   modified or freed.
  *
  * Since: 2.26
  *
@@ -881,8 +881,8 @@ g_settings_list_schemas (void)
  * Deprecated.
  *
  * Returns: (element-type utf8) (transfer none): a list of relocatable
- *   #GSettings schemas that are available.  The list must not be
- *   modified or freed.
+ *   #GSettings schemas that are available, in no defined order.  The list must
+ *   not be modified or freed.
  *
  * Since: 2.28
  *
@@ -1035,7 +1035,8 @@ g_settings_schema_has_key (GSettingsSchema *schema,
  * You should free the return value with g_strfreev() when you are done
  * with it.
  *
- * Returns: (transfer full) (element-type utf8): a list of the children on @settings
+ * Returns: (transfer full) (element-type utf8): a list of the children on
+ *    @settings, in no defined order
  *
  * Since: 2.44
  */
@@ -1080,7 +1081,7 @@ g_settings_schema_list_children (GSettingsSchema *schema)
  * function is intended for introspection reasons.
  *
  * Returns: (transfer full) (element-type utf8): a list of the keys on
- *   @schema
+ *   @schema, in no defined order
  *
  * Since: 2.46
  */