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

[Christian Brauner <brauner@kernel.org>]

On Fri, Jul 31, 2026 at 11:11:22AM +0200, Jori Koolstra wrote:
> 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?

The caller gives up ownership of reference of the dentry they passed.
Only the _return_ value can be used. On success you get the reference
for the same dentry back. On failure you get another dentry and the
reference of the dentry passed in is dropped. finish_no_open() is
documented similarly iirc.