GFileEnumerator: Add some documentation about ordering

Kind of a gratuitious gaping hole in the docs...

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

diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c
index d2779ce..b87335c 100644 (file)
--- a/gio/gfileenumerator.c
+++ b/gio/gfileenumerator.c
@@ -46,6 +46,17 @@
  * version will return a list of #GFileInfo<!---->s, whereas the 
  * synchronous will only return the next file in the enumerator.
  *
+ * The ordering of returned files is unspecified for non-Unix
+ * platforms; for more information, see g_dir_read_name().  On Unix,
+ * when operating on local files, returned files will be sorted by
+ * inode number.  Effectively you can assume that the ordering of
+ * returned files will be stable between successive calls (and
+ * applications) assuming the directory is unchanged.
+ *
+ * If your application needs a specific ordering, such as by name or
+ * modification time, you will have to implement that in your
+ * application code.
+ *
  * To close a #GFileEnumerator, use g_file_enumerator_close(), or 
  * its asynchronous version, g_file_enumerator_close_async(). Once 
  * a #GFileEnumerator is closed, no further actions may be performed 
@@ -180,6 +191,9 @@ g_file_enumerator_init (GFileEnumerator *enumerator)
  * returned from this function will contain attributes that match the 
  * attribute string that was passed when the #GFileEnumerator was created.
  *
+ * See the documentation of #GFileEnumerator for information about the
+ * order of returned files.
+ *
  * On error, returns %NULL and sets @error to the error. If the
  * enumerator is at the end, %NULL will be returned and @error will
  * be unset.
@@ -311,6 +325,9 @@ next_async_callback_wrapper (GObject      *source_object,
  * Request information for a number of files from the enumerator asynchronously.
  * When all i/o for the operation is finished the @callback will be called with
  * the requested information. 
+
+ * See the documentation of #GFileEnumerator for information about the
+ * order of returned files.
  *
  * The callback can be called with less than @num_files files in case of error
  * or at the end of the enumerator. In case of a partial error the callback will