[PATCH 2/3] fs/namei.c: fix kerneldoc of atomic_open() and vfs_lookup_open()

[Christian Brauner]

Commit ba0e87026613 ("fs/namei.c: update kerneldoc of atomic_open()")
turned the comment above atomic_open() into kerneldoc, but wrote the
return description as running text.  kernel-doc only recognises a return
section introduced by "Return:" or "Returns:", so this added a warning
under W=1:

  fs/namei.c:4362 No description found for return value of 'atomic_open'

Give it the missing colon.  The summary line also has to stand on its
own line, so move the "from a negative dentry" part into the body, where
it can say that the caller has to hand over a negative dentry.

Also add the "to" missing from vfs_lookup_open()'s description.

Fixes: ba0e87026613 ("fs/namei.c: update kerneldoc of atomic_open()")
Fixes: 536227b814bd ("VFS: add vfs_lookup_open() for nfsd")
Signed-off-by: Christian Brauner (Amutable) <brauner@xxxxxxxxxx>
---
 fs/namei.c | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/fs/namei.c b/fs/namei.c
index 226abf613983..e31905dfeb20 100644
--- a/fs/namei.c
+++ b/fs/namei.c
@@ -4337,8 +4337,7 @@ static int may_o_create(struct mnt_idmap *idmap,
 }
 
 /**
- * atomic_open() - attempt to atomically look up, create and open a file
- * from a negative dentry.
+ * atomic_open() - atomically look up, create and open a file
  * @path:          parent directory path
  * @dentry:        child to ->atomic_open()
  * @file:          file to attach child to
@@ -4346,6 +4345,9 @@ static int may_o_create(struct mnt_idmap *idmap,
  * @mode:          create mode
  * @create_error:  return value from may_o_create()
  *
+ * Attempt to look up, create and open @dentry, which must be negative, in a
+ * single call into the filesystem.
+ *
  * If a non-error dentry is returned then: when 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
@@ -4354,8 +4356,8 @@ static int may_o_create(struct mnt_idmap *idmap,
  * 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.
+ * Returns: the opened or looked-up dentry, or ERR_PTR() on failure.  The
+ * reference to @dentry is consumed in either case.
  */
 static struct dentry *atomic_open(const struct path *path, struct dentry *dentry,
 				  struct file *file,
@@ -4605,7 +4607,7 @@ static struct dentry *lookup_open(struct nameidata *nd, struct file *file,
  * @mode: initial permissions for file
  *
  * Open a file after lookup and/or create.  This provides similar
- * functionality open_last_lookups() for non-VFS users, particularly
+ * functionality to open_last_lookups() for non-VFS users, particularly
  * nfsd.
  * It uses ->atomic_open or ->lookup / ->create / ->open as appropriate.
  *

-- 
2.53.0