[PATCH v3 05/14] fs/namei.c: update docstring of atomic_open()

[Jori Koolstra <jkoolstra@xs4all.nl>]

The docstring of atomic_open() contains several errors:
  - It does not return 0 if successful.
  - path is not updated

Fix those and be more explicit about when FMODE_OPENED and FMODE_CREATED
are set.

Signed-off-by: Jori Koolstra <jkoolstra@xs4all.nl>
---
 fs/namei.c | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/fs/namei.c b/fs/namei.c
index 956adcd14c4a..88d56a470832 100644
--- a/fs/namei.c
+++ b/fs/namei.c
@@ -4355,17 +4355,24 @@ static int may_o_create(struct mnt_idmap *idmap,
 }
 
 /*
- * Attempt to atomically look up, create and open a file from a negative
- * dentry.
- *
- * Returns 0 if successful.  The file will have been created and attached to
- * @file by the filesystem calling finish_open().
- *
- * If the file was looked up only or didn't need creating, FMODE_OPENED won't
- * be set.  The caller will need to perform the open themselves.  @path will
- * have been updated to point to the new dentry.  This may be negative.
- *
- * Returns an error code otherwise.
+ * atomic_open() - attempt to atomically look up, create and open a file
+ * from a negative dentry.
+ * @path:          parent directory path
+ * @dentry:        child to ->atomic_open()
+ * @open_flag:     open flags
+ * @mode:          create mode
+ * @create_error:  return value from may_o_create()
+ *
+ * If FMODE_OPENED is set, the file will have been attached to @file by the
+ * filesystem calling finish_open(). If FMODE_OPENED isn't set, the
+ * filesystem instead called finish_no_open() and the caller will need to
+ * perform the open themselves.
+ *
+ * FMODE_CREATED is set when the call to ->atomic_open() actually created
+ * the file.
+ *
+ * Returns the opened/looked-up dentry on success or ERR_PTR(-E) on failure.
+ * On error, atomic_open() consumes @dentry.
  */
 static struct dentry *atomic_open(const struct path *path, struct dentry *dentry,
 				  struct file *file,
-- 
2.55.0