From acd0e6469a7270339119a4e350f73ba71a2903eb Mon Sep 17 00:00:00 2001
From: Nikolaus Rath <Nikolaus@rath.org>
Date: Wed, 12 Apr 2017 09:33:22 -0700
Subject: Improved documentation of fuse_context.private_data

In particular, don't call it "user_data" in one place and
"private_data" elsewhere.

Changing the name of the variable in the prototype should not affect
backwards compatibility.

Fixes: #155.
---
 include/fuse.h | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)

(limited to 'include')

diff --git a/include/fuse.h b/include/fuse.h
index 6bba1ce..754303f 100644
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -517,9 +517,10 @@ struct fuse_operations {
 	/**
 	 * Initialize filesystem
 	 *
-	 * The return value will passed in the private_data field of
-	 * fuse_context to all file operations and as a parameter to the
-	 * destroy() method.
+	 * The return value will passed in the `private_data` field of
+	 * `struct fuse_context` to all file operations, and as a
+	 * parameter to the destroy() method. It overrides the initial
+	 * value provided to fuse_main() / fuse_new().
 	 */
 	void *(*init) (struct fuse_conn_info *conn,
 		       struct fuse_config *cfg);
@@ -529,7 +530,7 @@ struct fuse_operations {
 	 *
 	 * Called on filesystem exit.
 	 */
-	void (*destroy) (void *);
+	void (*destroy) (void *private_data);
 
 	/**
 	 * Check file access permissions
@@ -767,17 +768,19 @@ struct fuse_context {
  * @param argc the argument counter passed to the main() function
  * @param argv the argument vector passed to the main() function
  * @param op the file system operation
- * @param user_data user data supplied in the context during the init() method
+ * @param private_data Initial value for the `private_data`
+ *            field of `struct fuse_context`. May be overriden by the
+ *            `struct fuse_operations.init` handler.
  * @return 0 on success, nonzero on failure
  *
  * Example usage, see hello.c
  */
 /*
   int fuse_main(int argc, char *argv[], const struct fuse_operations *op,
-  void *user_data);
+  void *private_data);
 */
-#define fuse_main(argc, argv, op, user_data)				\
-	fuse_main_real(argc, argv, op, sizeof(*(op)), user_data)
+#define fuse_main(argc, argv, op, private_data)				\
+	fuse_main_real(argc, argv, op, sizeof(*(op)), private_data)
 
 /* ----------------------------------------------------------- *
  * More detailed API					       *
@@ -805,11 +808,13 @@ struct fuse_context {
  * @param args argument vector
  * @param op the filesystem operations
  * @param op_size the size of the fuse_operations structure
- * @param user_data user data supplied in the context during the init() method
+ * @param private_data Initial value for the `private_data`
+ *            field of `struct fuse_context`. May be overriden by the
+ *            `struct fuse_operations.init` handler.
  * @return the created FUSE handle
  */
 struct fuse *fuse_new(struct fuse_args *args, const struct fuse_operations *op,
-		      size_t op_size, void *user_data);
+		      size_t op_size, void *private_data);
 
 /**
  * Mount a FUSE file system.
@@ -944,7 +949,7 @@ int fuse_interrupted(void);
  * Do not call this directly, use fuse_main()
  */
 int fuse_main_real(int argc, char *argv[], const struct fuse_operations *op,
-		   size_t op_size, void *user_data);
+		   size_t op_size, void *private_data);
 
 /**
  * Start the cleanup thread when using option "remember".
@@ -1082,11 +1087,13 @@ int fuse_notify_poll(struct fuse_pollhandle *ph);
  *
  * @param op the filesystem operations
  * @param op_size the size of the fuse_operations structure
- * @param user_data user data supplied in the context during the init() method
+ * @param private_data Initial value for the `private_data`
+ *            field of `struct fuse_context`. May be overriden by the
+ *            `struct fuse_operations.init` handler.
  * @return a new filesystem object
  */
 struct fuse_fs *fuse_fs_new(const struct fuse_operations *op, size_t op_size,
-			    void *user_data);
+			    void *private_data);
 
 /**
  * Factory for creating filesystem objects
-- 
cgit v1.2.3