Documentation fixes

doc/mainpage.dox

@@ -1,11 +1,11 @@
 /*!
 \mainpage FUSE API documentation
 
-Filesystem in Userspace (FUSE) is a loadable kernel module for Unix-like computer operating systems that lets non-privileged users create their own file systems without editing kernel code. This is achieved by running file system code in user space while the FUSE module provides only a "bridge" to the actual kernel interfaces. 
+Filesystem in Userspace (FUSE) is a loadable kernel module for Unix-like computer operating systems that lets non-privileged users create their own file systems without editing kernel code. This is achieved by running file system code in user space while the FUSE module provides only a "bridge" to the actual kernel interfaces.
 
 (c) Wikipedia
 
-@tableofcontents 
+@tableofcontents
 
 
 
@@ -22,7 +22,7 @@ Filesystem in Userspace (FUSE) is a loadable kernel module for Unix-like compute
 
 \section section2 Kernel
 
-\include kernel.txt 
+\include kernel.txt
 
 
 
@@ -57,31 +57,31 @@ have a look at the examples listed in the example directory, which can be found
 
 <a href="http://sourceforge.net/apps/mediawiki/fuse/index.php?title=Main_Page">http://sourceforge.net/apps/mediawiki/fuse/index.php?title=Main_Page</a> - the fuse wiki
 
-<a href="http://en.wikipedia.org/wiki/Filesystem_in_Userspace">http://en.wikipedia.org/wiki/Filesystem_in_Userspace</a> - FUSE on wikipedia 
+<a href="http://en.wikipedia.org/wiki/Filesystem_in_Userspace">http://en.wikipedia.org/wiki/Filesystem_in_Userspace</a> - FUSE on wikipedia
 
 
 \section section_todo todo
 
 general:
- 
+
  - fuse_lowlevel.h, describe:
   - a channel (or communication channel) is created by fuse_mount(..)
   - a fuse session is associated with a channel and a signal handler and runs until the assigned signal handler
     shuts the session down, see fuse_session_loop(se) and hello_ll.c
-    
+
  - http://www.cs.nmsu.edu/~pfeiffer/fuse-tutorial/
-    
+
  - http://cinwell.wordpress.com/
 
  - http://sourceforge.net/apps/mediawiki/fuse/index.php?title=FuseProtocolSketch
 
  - http://muratbuffalo.blogspot.de/2011/05/refuse-to-crash-with-re-fuse.html
 
 examples:
- - demonstrate the effect of single vs multithreaded -> fuse_loop fuse_loop_mt 
+ - demonstrate the effect of single vs multithreaded -> fuse_loop fuse_loop_mt
 
  - add comments and source form all existing examples
- 
+
  - also add examples form here: http://sourceforge.net/apps/mediawiki/fuse/index.php?title=Main_Page#How_should_threads_be_startedx3f
 
  - add this new example: http://fuse.996288.n3.nabble.com/Create-multiple-filesystems-in-same-process-td9292.html

example/fioc.c

@@ -18,7 +18,7 @@
  * gcc -Wall fioc.c `pkg-config fuse --cflags --libs` -o fioc
  *
  * \section section_source the complete source
- * \include fioc.c 
+ * \include fioc.c
  */
 
 

example/fioc.h

@@ -11,7 +11,7 @@
  * @tableofcontents
  *
  * fioc.h - FUSE-ioctl: ioctl support for FUSE
- * 
+ *
  * \include fioc.h
  */
 

example/hello.c

@@ -108,15 +108,13 @@ static int hello_read(const char *path, char *buf, size_t size, off_t offset,
 	return size;
 }
 
-// fuse_operations hello_oper is redirecting function-calls to _our_ functions implemented above
 static struct fuse_operations hello_oper = {
 	.getattr	= hello_getattr,
 	.readdir	= hello_readdir,
 	.open		= hello_open,
 	.read		= hello_read,
 };
 
-// in the main function we call the blocking fuse_main(..) function with &hello_oper 
 int main(int argc, char *argv[])
 {
 	return fuse_main(argc, argv, &hello_oper, NULL);

example/hello_ll.c

@@ -9,9 +9,9 @@
 /** @file
  *
  * hello_ll.c - fuse low level functionality
- * 
+ *
  * unlike hello.c this example will stay in the foreground. it also replaced
- * the convenience function fuse_main(..) with a more low level approach.  
+ * the convenience function fuse_main(..) with a more low level approach.
  *
  * \section section_compile compiling this example
  *
@@ -20,7 +20,7 @@
  * \section section_usage usage
  \verbatim
  % mkdir mnt
- % ./hello_ll mnt        # program will wait in foreground until you press CTRL+C
+ % ./hello_ll mnt       # program will wait in foreground until you press CTRL+C
  in a different shell do:
  % ls -la mnt
    total 4
@@ -191,15 +191,16 @@ int main(int argc, char *argv[])
 	if (fuse_parse_cmdline(&args, &mountpoint, NULL, NULL) != -1 &&
 	    (ch = fuse_mount(mountpoint, &args)) != NULL) {
 		struct fuse_session *se;
+
 		se = fuse_lowlevel_new(&args, &hello_ll_oper,
 				       sizeof(hello_ll_oper), NULL);
 		if (se != NULL) {
 			if (fuse_set_signal_handlers(se) != -1) {
 				fuse_session_add_chan(se, ch);
-				
-				/* fuse_session_loop(..) blocks until ctrl+c or fusermount -u */
-				err = fuse_session_loop(se); 
-				
+
+				/* Block until ctrl+c or fusermount -u */
+				err = fuse_session_loop(se);
+
 				fuse_remove_signal_handlers(se);
 				fuse_session_remove_chan(ch);
 			}

example/null.c

@@ -8,7 +8,7 @@
 
 /** @file
  *
- * null.c - FUSE: Filesystem in Userspace 
+ * null.c - FUSE: Filesystem in Userspace
  *
  * \section section_compile compiling this example
  *

include/fuse.h

@@ -114,7 +114,7 @@ struct fuse_operations {
 	 */
 	int (*mknod) (const char *, mode_t, dev_t);
 
-	/** Create a directory 
+	/** Create a directory
 	 *
 	 * Note that the mode argument may not have the type specification
 	 * bits set, i.e. S_ISDIR(mode) can be false.  To obtain the
@@ -589,7 +589,7 @@ struct fuse_context {
  * @param op the file system operation
  * @param user_data user data supplied in the context during the init() method
  * @return 0 on success, nonzero on failure
- * 
+ *
  * Example usage, see hello.c
  */
 /*
@@ -637,7 +637,7 @@ void fuse_destroy(struct fuse *f);
  *
  * @param f the FUSE handle
  * @return 0 if no error occurred, -1 otherwise
- * 
+ *
  * See also: fuse_loop()
  */
 int fuse_loop(struct fuse *f);
@@ -658,27 +658,24 @@ void fuse_exit(struct fuse *f);
  *
  * Calling this function requires the pthreads library to be linked to
  * the application.
- * 
- * Note: using fuse_loop() instead of fuse_loop_mt() means you are running in single-threaded mode, 
- * and that you will not have to worry about reentrancy, 
- * though you will have to worry about recursive lookups. In single-threaded mode, FUSE 
- * holds a global lock on your filesystem, and will wait for one callback to return 
- * before calling another. This can lead to deadlocks, if your script makes any attempt 
- * to access files or directories in the filesystem it is providing. 
- * (This includes calling stat() on the mount-point, statfs() calls from the 'df' command, 
- * and so on and so forth.) It is worth paying a little attention and being careful about this.
- * 
- * Enabling multiple threads, by using fuse_loop_mt(), will cause FUSE to make multiple simultaneous 
- * calls into the various callback functions given by your fuse_operations record. 
- * 
- * If you are using multiple threads, you can enjoy all the parallel execution and interactive 
- * response benefits of threads, and you get to enjoy all the benefits of race conditions 
- * and locking bugs, too. Ensure that any code used in the callback funtion of fuse_operations 
- * is also thread-safe.
+ *
+ * Note: using fuse_loop() instead of fuse_loop_mt() means you are running in
+ * single-threaded mode, and that you will not have to worry about reentrancy,
+ * though you will have to worry about recursive lookups. In single-threaded
+ * mode, FUSE will wait for one callback to return before calling another.
+ *
+ * Enabling multiple threads, by using fuse_loop_mt(), will cause FUSE to make
+ * multiple simultaneous calls into the various callback functions given by your
+ * fuse_operations record.
+ *
+ * If you are using multiple threads, you can enjoy all the parallel execution
+ * and interactive response benefits of threads, and you get to enjoy all the
+ * benefits of race conditions and locking bugs, too. Ensure that any code used
+ * in the callback funtion of fuse_operations is also thread-safe.
  *
  * @param f the FUSE handle
  * @return 0 if no error occurred, -1 otherwise
- * 
+ *
  * See also: fuse_loop()
  */
 int fuse_loop_mt(struct fuse *f);

include/fuse_common.h

@@ -451,12 +451,13 @@ ssize_t fuse_buf_copy(struct fuse_bufvec *dst, struct fuse_bufvec *src,
  * Stores session in a global variable.	 May only be called once per
  * process until fuse_remove_signal_handlers() is called.
  *
- * Once either of the POSIX signals arrives, the exit_handler() in fuse_signals.c is called:
+ * Once either of the POSIX signals arrives, the exit_handler() in
+ * fuse_signals.c is called:
  * \snippet fuse_signals.c doxygen_exit_handler
- * 
+ *
  * @param se the session to exit
  * @return 0 on success, -1 on failure
- * 
+ *
  * See also:
  * fuse_remove_signal_handlers()
  */
@@ -469,7 +470,7 @@ int fuse_set_signal_handlers(struct fuse_session *se);
  * be called again.
  *
  * @param se the same session as given in fuse_set_signal_handlers()
- * 
+ *
  * See also:
  * fuse_set_signal_handlers()
  */

include/fuse_lowlevel.h

@@ -1566,7 +1566,7 @@ int fuse_req_interrupted(fuse_req_t req);
  * @param userdata user data
  * @return the created session object, or NULL on failure
  *
- * Example: See hello_ll.c: 
+ * Example: See hello_ll.c:
  *   \snippet hello_ll.c doxygen_fuse_lowlevel_usage
  */
 struct fuse_session *fuse_lowlevel_new(struct fuse_args *args,
@@ -1638,9 +1638,10 @@ int fuse_session_receive_buf(struct fuse_session *se, struct fuse_buf *buf,
 void fuse_session_destroy(struct fuse_session *se);
 
 /**
- * Exit a session. This function is invoked by the POSIX signal handlers, when registered using:
+ * Exit a session.
+ *
+ * This function is invoked by the POSIX signal handlers, when registered using:
  * * fuse_set_signal_handlers()
- * * fuse_remove_signal_handlers()
  *
  * @param se the session
  */
@@ -1665,8 +1666,8 @@ int fuse_session_exited(struct fuse_session *se);
  * Enter a single threaded, blocking event loop.
  *
  * Using POSIX signals this event loop can be exited but the session
- * needs to be configued by issuing: 
- *   fuse_set_signal_handlers() first. 
+ * needs to be configued by issuing:
+ *   fuse_set_signal_handlers() first.
  *
  * @param se the session
  * @return 0 on success, -1 on error