Re: GDir as DIR replacement - patch

[Owen Taylor <otaylor redhat com>]

Hans Breuer <hans breuer org> writes:

> At 19:11 04.11.01 -0500, Owen Taylor wrote:
> >> [...]
> >
> >OK, I think it makes sense to go ahead and squeeze this in. Will
> >you be able to do another version of the patch in the next day
> >or so? 
> Even in the next hour or so, maybe I need to sleep at work in
> some hours :-)
> 
> IMO it is the simpliest solution if I deliver the files
> through cvs, probably done before this mail arrives.

In the same spirit, I took the liberty of commiting the appended
patch. It has a bunch of style fixes for docs and indentation
and also removes the boolean return value from g_dir_close().

I'll fix Makefile.am, glib.h, and configure.in now.

Regards,
                                        Owen

Sun Nov  4 20:29:31 2001  Owen Taylor  <otaylor redhat com>

	* glib/gdir.[ch]: Indentation fixes, some rewriting of docs to
	conform to gtk-doc standard.

	* glib/gdir.[ch] (g_dir_close): Remove the boolean 
	return value. What would you do if closing failed?
	What would the user do if you printed a warning
	message "closing directory %s failed"?


Index: gdir.c
===================================================================
RCS file: /cvs/gnome/glib/glib/gdir.c,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -p -r1.1 -r1.2
--- gdir.c	2001/11/05 01:15:38	1.1
+++ gdir.c	2001/11/05 01:35:30	1.2
@@ -35,17 +35,24 @@
 
 struct _GDir
 {
-  /*< private >*/
   DIR *dir;
 };
 
 /**
  * g_dir_open:
  * @path: the path to the directory you are interested in
- * @flags: for future binary compatible extensions 
- * @error: return location for a #GError
- *
- * Return value: a #GDir* on success, NULL if error is set
+ * @flags: Currently must be set to 0. Reserved for future use.
+ * @error: return location for a #GError, or %NULL.
+ *         If non-%NULL, an error will be set if and only if
+ *         g_dir_open_fails.
+ *
+ * Opens a directory for reading. The names of the files
+ * in the directory can then be retrieved using
+ * g_dir_get_name().
+ *
+ * Return value: a newly allocated #GDir on success, %NULL on failure.
+ *   If non-%NULL, you must free the result with g_dir_close()
+ *   when you are finished with it.
  **/
 GDir *
 g_dir_open (const gchar  *path,
@@ -63,8 +70,8 @@ g_dir_open (const gchar  *path,
   g_set_error (error,
                G_FILE_ERROR,
                g_file_error_from_errno (errno),
-               _("Error opening dir '%s': %s"),
-                 path, strerror (errno));
+               _("Error opening directory '%s': %s"),
+	       path, strerror (errno));
 
   g_free (dir);
   return NULL;
@@ -73,18 +80,16 @@ g_dir_open (const gchar  *path,
 /**
  * g_dir_read_name:
  * @dir: a #GDir* created by g_dir_open()
- *
- * Iterator which delivers the next directory entries name
- * with each call. The '.' and '..' entries are omitted.
  *
- * BTW: using these functions will simplify porting of
- * your app, at least to Windows.
+ * Retrieves the name of the next entry in the directory.
+ * The '.' and '..' entries are omitted.
  *
- * Return value: The entries name or NULL if there are no 
- * more entries. Don't free this value!
+ * Return value: The entries name or %NULL if there are no 
+ *   more entries. The return value is owned by GLib and
+ *   must not be modified or freed.
  **/
 G_CONST_RETURN gchar*
-g_dir_read_name (GDir    *dir)
+g_dir_read_name (GDir *dir)
 {
   struct dirent *entry;
 
@@ -92,8 +97,8 @@ g_dir_read_name (GDir    *dir)
 
   entry = readdir (dir->dir);
   while (entry 
-         && (   0 == strcmp (entry->d_name, ".") 
-             || 0 == strcmp (entry->d_name, "..")))
+         && (0 == strcmp (entry->d_name, ".") ||
+             0 == strcmp (entry->d_name, "..")))
     entry = readdir (dir->dir);
 
   return entry->d_name;
@@ -119,18 +124,14 @@ g_dir_rewind (GDir *dir)
  * @dir: a #GDir* created by g_dir_open()
  *
  * Closes the directory and deallocates all related resources.
- *
- * Return value: TRUE on success, FALSE otherwise.
  **/
-gboolean
+void
 g_dir_close (GDir *dir)
 {
   int ret = 0;
 
   g_return_val_if_fail (dir != NULL, FALSE);
 
-  ret = closedir (dir->dir);
+  closedir (dir->dir);
   g_free (dir);
-
-  return !ret; 
 }
Index: gdir.h
===================================================================
RCS file: /cvs/gnome/glib/glib/gdir.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -p -r1.1 -r1.2
--- gdir.h	2001/11/05 01:15:38	1.1
+++ gdir.h	2001/11/05 01:35:30	1.2
@@ -7,11 +7,12 @@ G_BEGIN_DECLS
 
 typedef struct _GDir GDir;
 
-GDir    *g_dir_open (const gchar *path, guint flags, GError **error);
-G_CONST_RETURN
-gchar   *g_dir_read_name (GDir *dir);
-void     g_dir_rewind (GDir *dir);
-gboolean g_dir_close (GDir *dir);
+GDir    *               g_dir_open      (const gchar  *path,
+					 guint         flags,
+					 GError      **error);
+G_CONST_RETURN gchar   *g_dir_read_name (GDir         *dir);
+void                    g_dir_rewind    (GDir         *dir);
+void                    g_dir_close     (GDir         *dir);
 
 G_END_DECLS