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

[Jori Koolstra <jkoolstra@xs4all.nl>]

Hi Christian,

> Op 31-07-2026 10:36 CEST schreef Christian Brauner <brauner@kernel.org>:
> 
>  
> 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@kernel.org>
> ---
>  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.

Is this true? Maybe I am confused about the semantics of "consumed." If a function
returns a dentry (or anything else refcounted), without dput()-ing it (or whatever),
does that count as consuming that dentry in that function?

It's not mentioned in the commit log, that's why I ask :)

Thanks for the fixup!

Best,
Jori.