From e20e5c9ae574bba8827310edf38ae9edca08c469 Mon Sep 17 00:00:00 2001
From: Nikolaus Rath <Nikolaus@rath.org>
Date: Sat, 1 Oct 2016 11:24:46 -0700
Subject: Improve documentation of argument parsing.

---
 include/fuse.h          |  7 +++++++
 include/fuse_common.h   | 16 +++++++++++++---
 include/fuse_lowlevel.h |  7 +++++++
 3 files changed, 27 insertions(+), 3 deletions(-)

(limited to 'include')

diff --git a/include/fuse.h b/include/fuse.h
index c70d2fe..5721caa 100644
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -640,6 +640,13 @@ struct fuse_context {
 /**
  * Create a new FUSE filesystem.
  *
+ * Known parameters in `args` are removed. If there are any unknown
+ * arguments, an error is printed to stderr and the function returns
+ * NULL.
+ *
+ * If the --help or --version parameters are specified, the function
+ * prints the requested information to stdout and returns NULL.
+ *
  * @param ch the communication channel
  * @param args argument vector
  * @param op the filesystem operations
diff --git a/include/fuse_common.h b/include/fuse_common.h
index 2fa9962..df92e8e 100644
--- a/include/fuse_common.h
+++ b/include/fuse_common.h
@@ -213,7 +213,13 @@ struct fuse_pollhandle;
  * Create a FUSE mountpoint
  *
  * Returns a control file descriptor suitable for passing to
- * fuse_new()
+ * fuse_new(). Unknown parameters in `args` are passed through
+ * unchanged. Known parameters (with the exception of --help and
+ * --version) are removed from `args`.
+ *
+ * If the --help or --version parameters are specified, the function
+ * prints the requested information to stdout and returns a valid
+ * pointer. However, it does not actually perform the mount.
  *
  * @param mountpoint the mount point path
  * @param args argument vector
@@ -230,7 +236,7 @@ struct fuse_chan *fuse_mount(const char *mountpoint, struct fuse_args *args);
 void fuse_unmount(const char *mountpoint, struct fuse_chan *ch);
 
 /**
- * Parse common options
+ * Utility functions for simple file systems to parse common options.
  *
  * The following options are parsed:
  *
@@ -242,7 +248,11 @@ void fuse_unmount(const char *mountpoint, struct fuse_chan *ch);
  *   '-ofsname=..'   file system name, if not present, then set to the program
  *		     name
  *
- * All parameters may be NULL
+ * Unknown parameters in `args` are passed through unchanged. Known
+ * parameters (with the exception of --help and --version) are removed.
+ *
+ * All parameters may be NULL (in which case they may still
+ * be specified on the command line, but will not be set).
  *
  * @param args argument vector
  * @param mountpoint the returned mountpoint, should be freed after use
diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index 2022cc6..ce39906 100644
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -1575,6 +1575,13 @@ int fuse_req_interrupted(fuse_req_t req);
 /**
  * Create a low level session
  *
+ * Known parameters in `args` are removed. If there are any unknown
+ * arguments, an error is printed to stderr and the function returns
+ * NULL.
+ *
+ * If the --help or --version parameters are specified, the function
+ * prints the requsted information to stdout and returns NULL.
+ *
  * @param args argument vector
  * @param op the low level filesystem operations
  * @param op_size sizeof(struct fuse_lowlevel_ops)
-- 
cgit v1.2.3