Improve the g_dir_read_name documentation

This function can return NULL in error cases as well. Document
this, and explain how to discriminate the cases.
https://bugzilla.gnome.org/show_bug.cgi?id=639771

diff --git a/glib/gdir.c b/glib/gdir.c
index 3173ae7..e89de89 100644 (file)
--- a/glib/gdir.c
+++ b/glib/gdir.c
@@ -188,7 +188,11 @@ g_dir_open (const gchar  *path,
  * Retrieves the name of another entry in the directory, or %NULL.
  * The order of entries returned from this function is not defined,
  * and may vary by file system or other operating-system dependent
- * factors. 
+ * factors.
+ *
+ * %NULL may also be returned in case of errors. On Unix, you can
+ * check <literal>errno</literal> to find out if %NULL was returned
+ * because of an error.
  *
  * On Unix, the '.' and '..' entries are omitted, and the returned
  * name is in the on-disk encoding.
@@ -196,7 +200,7 @@ g_dir_open (const gchar  *path,
  * On Windows, as is true of all GLib functions which operate on
  * filenames, the returned name is in UTF-8.
  *
- * Return value: The entry's name or %NULL if there are no 
+ * Return value: The entry's name or %NULL if there are no
  *   more entries. The return value is owned by GLib and
  *   must not be modified or freed.
  **/