glibmm r632 - in trunk: . gio/src

[murrayc svn gnome org]

Author: murrayc
Date: Tue Mar  4 13:29:51 2008
New Revision: 632
URL: http://svn.gnome.org/viewvc/glibmm?rev=632&view=rev

Log:
2008-03-04  Murray Cumming  <murrayc murrayc com>

* gio/src/gio_docs.xml: Regenerated with docextract_to_xml.py.
* gio/src/gio_docs_override.xml: Overrode g_file_query_exists() to 
mention an exception instead of an error. G_IO_ERROR_* now does not 
appear in any of our documentation.

Modified:
   trunk/ChangeLog
   trunk/gio/src/gio_docs.xml
   trunk/gio/src/gio_docs_override.xml

Modified: trunk/gio/src/gio_docs.xml
==============================================================================
--- trunk/gio/src/gio_docs.xml	(original)
+++ trunk/gio/src/gio_docs.xml	Tue Mar  4 13:29:51 2008
@@ -2141,7 +2141,8 @@
 
 <function name="g_file_delete">
 <description>
-Deletes a file.
+Deletes a file. If the @file is a directory, it will only be deleted if it 
+is empty.
 
 If @cancellable is not %NULL, then the operation can be cancelled by
 triggering the cancellable object from another thread. If the operation
@@ -8194,7 +8195,7 @@
 
 On failure the first error that happened will be reported, but the close
 operation will finish as much as possible. A stream that failed to
-close will still return %G_IO_ERROR_CLOSED all operations. Still, it
+close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
 is important to check and report the error to the user, otherwise
 there might be a loss of data as all data might not be written.
 
@@ -9802,7 +9803,7 @@
 
 On failure the first error that happened will be reported, but the close
 operation will finish as much as possible. A stream that failed to
-close will still return %G_IO_ERROR_CLOSED all operations. Still, it
+close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
 is important to check and report the error to the user.
 
 If @cancellable is not NULL, then the operation can be cancelled by

Modified: trunk/gio/src/gio_docs_override.xml
==============================================================================
--- trunk/gio/src/gio_docs_override.xml	(original)
+++ trunk/gio/src/gio_docs_override.xml	Tue Mar  4 13:29:51 2008
@@ -1692,5 +1692,46 @@
 </return>
 </function>
 
+<function name="g_file_query_exists">
+<description>
+Utility function to check if a particular file exists. This is
+implemented using query_info() and as such does blocking I/O.
+
+Note that in many cases it is racy to first check for file existence
+and then execute something based on the outcome of that, because the
+file might have been created or removed in between the operations. The
+general approach to handling that is to not check, but just do the
+operation and handle the errors as they come.
+
+As an example of race-free checking, take the case of reading a file, and
+if it doesn&apos;t exist, creating it. There are two racy versions: read it, and
+on error create it; and: check if it exists, if not create it. These
+can both result in two processes creating the file (with perhaps a partially
+written file as the result). The correct approach is to always try to create
+the file with File::create() which will either atomically create the file
+or fail with a Gio::Error exception with EXISTS.
+
+However, in many cases an existence check is useful in a user
+interface, for instance to make a menu item sensitive/insensitive, so that
+you don&apos;t have to fool users that something is possible and then just show
+and error dialog. If you do this, you should make sure to also handle the
+errors that can happen due to races when you execute the operation.
+
+
+</description>
+<parameters>
+<parameter name="file">
+<parameter_description> input #GFile.
+</parameter_description>
+</parameter>
+<parameter name="cancellable">
+<parameter_description> optional #GCancellable object, %NULL to ignore.
+</parameter_description>
+</parameter>
+</parameters>
+<return> %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled).
+</return>
+</function>
+
 
 </root>