Re: Can someone please comment on this short program

[Murray Cumming <murrayc murrayc com>]

On Thu, 2005-12-15 at 20:37 +0100, Murray Cumming wrote:
> > We should sprinkle all the relevant docs with examples...
> 
> This is why I'm asking. I'll try to finish a patch tomorrow.

This patch mentions stuff mentioned in this thread, with suggestions
about what functions might provide the URIs/filenames in the desired
formats, and/or what functions might be able to use the results.

Actually the documentation is pretty good already.

-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com

? compile
? gnome-vfs-zip
? imported/fnmatch/Makefile
? imported/fnmatch/Makefile.in
? imported/neon/Makefile
? imported/neon/Makefile.in
? po/stamp-it
? test/test-address
? test/test-parse-ls-lga
Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/gnome-vfs/ChangeLog,v
retrieving revision 1.2328
diff -u -p -r1.2328 ChangeLog
--- ChangeLog	14 Dec 2005 15:14:10 -0000	1.2328
+++ ChangeLog	19 Dec 2005 12:44:05 -0000
@@ -1,3 +1,10 @@
+2005-12-19  Murray Cumming  <murrayc murrayc com>
+
+	* libgnomevfs/gnome-vfs-uri.c:
+	* libgnomevfs/gnome-vfs-utils.c: Expand some documentation 
+	to make it clearer what types of strings are expected/provided 
+	by some functions.
+
 2005-12-14  Alexander Larsson  <alexl redhat com>
 
 	* configure.in:
Index: libgnomevfs/gnome-vfs-uri.c
===================================================================
RCS file: /cvs/gnome/gnome-vfs/libgnomevfs/gnome-vfs-uri.c,v
retrieving revision 1.131
diff -u -p -r1.131 gnome-vfs-uri.c
--- libgnomevfs/gnome-vfs-uri.c	26 Nov 2005 19:32:23 -0000	1.131
+++ libgnomevfs/gnome-vfs-uri.c	19 Dec 2005 12:44:05 -0000
@@ -491,11 +491,15 @@ parse_uri_substring (const gchar *substr
 
 /**
  * gnome_vfs_uri_new:
- * @text_uri: a string representing a uri.
+ * @text_uri: an escaped string representing a uri.
  * 
  * Create a new uri from @text_uri. Unsupported and unsafe methods
  * are not allowed and will result in %NULL being returned. URL
  * transforms are allowed.
+ *
+ * The @a text_uri must be an escaped URI string such as returned by 
+ * gnome_vfs_get_uri_from_local_path(), gnome_vfs_make_uri_from_input(), 
+ * or gtk_file_chooser_get_uri().
  * 
  * Return value: The new uri.
  */
@@ -1117,11 +1121,12 @@ gnome_vfs_uri_append_path (const GnomeVF
 /**
  * gnome_vfs_uri_append_file_name:
  * @uri: a #GnomeVFSURI.
- * @filename: any "regular" file name (can include #, /, etc).
+ * @filename: any "regular" file name (can include #, /, etc) in the file system encoding. This is not an escaped URI.
  * 
  * Create a new uri obtained by appending @file_name to @uri.  This will take care
  * of adding an appropriate directory separator between the end of @uri and
- * the start of @file_name if necessary.
+ * the start of @file_name if necessary. @file_name might, for instance, be the 
+ * result of a call to g_dir_read_name().
  * 
  * Return value: The new uri obtained by combining @uri and @path.
  */
Index: libgnomevfs/gnome-vfs-utils.c
===================================================================
RCS file: /cvs/gnome/gnome-vfs/libgnomevfs/gnome-vfs-utils.c,v
retrieving revision 1.105
diff -u -p -r1.105 gnome-vfs-utils.c
--- libgnomevfs/gnome-vfs-utils.c	14 Nov 2005 11:41:13 -0000	1.105
+++ libgnomevfs/gnome-vfs-utils.c	19 Dec 2005 12:44:05 -0000
@@ -771,11 +771,13 @@ gnome_vfs_get_local_path_from_uri (const
 /**
  * gnome_vfs_get_uri_from_local_path:
  * @local_full_path: a full local filesystem path (i.e. not relative).
+ * 
+ * Returns a file:/// URI for the local path @local_full_path, 
+ * such as a path provided by gtk_file_chooser_get_filename().
+ * The resulting URI may be provided, for instance, to gnome_vfs_uri_new().
  *
- * On Windows this should be in the UTF-8 encoding, and can start with a drive
+ * On Windows @local_full_path should be in the UTF-8 encoding, and can start with a drive
  * letter, but doesn't have to.
- * 
- * Returns a file:/// uri for the local path @local_full_path.
  *
  * Return value: a newly allocated string containing the uri corresponding 
  * to @local_full_path (%NULL for some bad errors).