Various documentation improvements

See issue #389 for some related discussions.

2 files changed, 28 insertions, 18 deletions

diff --git a/include/fuse.h b/include/fuse.h
index 3e8aa20..2d2291c 100644
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -66,7 +66,7 @@ enum fuse_fill_dir_flags {
 
 /** Function to add an entry in a readdir() operation
  *
- * The *off* parameter can be any non-zero value that enableds the
+ * The *off* parameter can be any non-zero value that enables the
  * filesystem to identify the current point in the directory
  * stream. It does not need to be the actual physical position. A
  * value of zero is reserved to indicate that seeking in directories
@@ -220,7 +220,7 @@ struct fuse_config {
 	/**
 	 * This option disables flushing the cache of the file
 	 * contents on every open(2).  This should only be enabled on
-	 * filesystems, where the file data is never changed
+	 * filesystems where the file data is never changed
 	 * externally (not through the mounted FUSE filesystem).  Thus
 	 * it is not suitable for network filesystems and other
 	 * intermediate filesystems.
@@ -394,12 +394,11 @@ struct fuse_operations {
 	 *  - Creation (O_CREAT, O_EXCL, O_NOCTTY) flags will be
 	 *    filtered out / handled by the kernel.
 	 *
-	 *  - Access modes (O_RDONLY, O_WRONLY, O_RDWR) should be used
-	 *    by the filesystem to check if the operation is
-	 *    permitted.  If the ``-o default_permissions`` mount
-	 *    option is given, this check is already done by the
-	 *    kernel before calling open() and may thus be omitted by
-	 *    the filesystem.
+	 *  - Access modes (O_RDONLY, O_WRONLY, O_RDWR, O_EXEC, O_SEARCH)
+	 *    should be used by the filesystem to check if the operation is
+	 *    permitted.  If the ``-o default_permissions`` mount option is
+	 *    given, this check is already done by the kernel before calling
+	 *    open() and may thus be omitted by the filesystem.
 	 *
 	 *  - When writeback caching is enabled, the kernel may send
 	 *    read requests even for files opened with O_WRONLY. The
@@ -483,9 +482,9 @@ struct fuse_operations {
 	 *
 	 * NOTE: The flush() method may be called more than once for each
 	 * open().  This happens if more than one file descriptor refers to an
-	 * opened file, e.g. due to dup(), dup2() or fork() calls.  It is not
-	 * possible to determine if a flush is final, so each flush should be
-	 * treated equally.  Multiple write-flush sequences are relatively
+	 * open file handle, e.g. due to dup(), dup2() or fork() calls.  It is
+	 * not possible to determine if a flush is final, so each flush should
+	 * be treated equally.  Multiple write-flush sequences are relatively
 	 * rare, so this shouldn't be a problem.
 	 *
 	 * Filesystems shouldn't assume that flush will be called at any
@@ -503,7 +502,7 @@ struct fuse_operations {
 	 * are unmapped.
 	 *
 	 * For every open() call there will be exactly one release() call
-	 * with the same flags and file descriptor.	 It is possible to
+	 * with the same flags and file handle.  It is possible to
 	 * have a file opened more than once, in which case only the last
 	 * release will mean, that no more reads/writes will happen on the
 	 * file.  The return value of release is ignored.
@@ -794,7 +793,7 @@ struct fuse_context {
 	/** Group ID of the calling process */
 	gid_t gid;
 
-	/** Thread ID of the calling process */
+	/** Process ID of the calling thread */
 	pid_t pid;
 
 	/** Private filesystem data */
diff --git a/include/fuse_common.h b/include/fuse_common.h
index 83c9dee..5cf9fee 100644
--- a/include/fuse_common.h
+++ b/include/fuse_common.h
@@ -32,14 +32,24 @@ extern "C" {
 #endif
 
 /**
- * Information about open files
+ * Information about an open file.
+ *
+ * File Handles are created by the open, opendir, and create methods and closed
+ * by the release and releasedir methods.  Multiple file handles may be
+ * concurrently open for the same file.  Generally, a client will create one
+ * file handle per file descriptor, though in some cases multiple file
+ * descriptors can share a single file handle.
  */
 struct fuse_file_info {
 	/** Open flags.	 Available in open() and release() */
 	int flags;
 
-	/** In case of a write operation indicates if this was caused by a
-	    writepage */
+	/** In case of a write operation indicates if this was caused
+	    by a delayed write from the page cache. If so, then the
+	    context's pid, uid, and gid fields will not be valid, and
+	    the *fh* value may not match the *fh* value that would
+	    have been sent with the corresponding individual write
+	    requests if write caching had been disabled. */
 	unsigned int writepage : 1;
 
 	/** Can be filled in by open, to use direct I/O on this file. */
@@ -67,8 +77,9 @@ struct fuse_file_info {
 	/** Padding.  Do not use*/
 	unsigned int padding : 27;
 
-	/** File handle.  May be filled in by filesystem in open().
-	    Available in all other file operations */
+	/** File handle id.  May be filled in by filesystem in create,
+	 * open, and opendir().  Available in most other file operations on the
+	 * same file handle. */
 	uint64_t fh;
 
 	/** Lock owner id.  Available in locking operations and flush */