- added a doxygen main page

- modified all examples to be included in doxygen
- modified the API documentation to have more details
- added the 490px_FUSE_structure.svg.png (c) wikipedia

3 files changed, 43 insertions, 2 deletions

diff --git a/include/fuse.h b/include/fuse.h
index 793862e..c7647ce 100644
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -589,6 +589,8 @@ 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
  */
 /*
   int fuse_main(int argc, char *argv[], const struct fuse_operations *op,
@@ -635,6 +637,8 @@ 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);
 
@@ -654,9 +658,28 @@ 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.
  *
  * @param f the FUSE handle
  * @return 0 if no error occurred, -1 otherwise
+ * 
+ * See also: fuse_loop()
  */
 int fuse_loop_mt(struct fuse *f);
 
diff --git a/include/fuse_common.h b/include/fuse_common.h
index af16203..9fd4bbb 100644
--- a/include/fuse_common.h
+++ b/include/fuse_common.h
@@ -451,8 +451,14 @@ 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:
+ * \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()
  */
 int fuse_set_signal_handlers(struct fuse_session *se);
 
@@ -463,6 +469,9 @@ 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()
  */
 void fuse_remove_signal_handlers(struct fuse_session *se);
 
diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index d46ef86..ada5ce8 100644
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -1565,6 +1565,9 @@ int fuse_req_interrupted(fuse_req_t req);
  * @param op_size sizeof(struct fuse_lowlevel_ops)
  * @param userdata user data
  * @return the created session object, or NULL on failure
+ *
+ * Example: See hello_ll.c: 
+ *   \snippet hello_ll.c doxygen_fuse_lowlevel_usage
  */
 struct fuse_session *fuse_lowlevel_new(struct fuse_args *args,
 				       const struct fuse_lowlevel_ops *op,
@@ -1707,7 +1710,9 @@ int fuse_session_receive_buf(struct fuse_session *se, struct fuse_buf *buf,
 void fuse_session_destroy(struct fuse_session *se);
 
 /**
- * Exit a session
+ * 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
  */
@@ -1737,7 +1742,11 @@ int fuse_session_exited(struct fuse_session *se);
 void *fuse_session_data(struct fuse_session *se);
 
 /**
- * Enter a single threaded event loop
+ * 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. 
  *
  * @param se the session
  * @return 0 on success, -1 on error