[PATCH] fs: doc: describe 'pinned' parameter in do_lock_mount()

[PATCH] fs: doc: describe 'pinned' parameter in do_lock_mount()

[Kriish Sharma]

The kernel-doc comment for do_lock_mount() was missing a description
for the 'pinned' parameter:

  Warning: fs/namespace.c:2772 function parameter 'pinned' not described
  in 'do_lock_mount'

This patch adds a short description:

  @pinned: receives the pinned mountpoint

to fix the warning and improve documentation clarity.

Signed-off-by: Kriish Sharma <kriish.sharma2006@gmail.com>
---
 fs/namespace.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/fs/namespace.c b/fs/namespace.c
index 51f77c65c0c6..4de1a33ab516 100644
--- a/fs/namespace.c
+++ b/fs/namespace.c
@@ -2738,6 +2738,7 @@ static int attach_recursive_mnt(struct mount *source_mnt,
 /**
  * do_lock_mount - lock mount and mountpoint
  * @path:    target path
+ * @pinned:  receives the pinned mountpoint
  * @beneath: whether the intention is to mount beneath @path
  *
  * Follow the mount stack on @path until the top mount @mnt is found. If
-- 
2.34.1

Re: [PATCH] fs: doc: describe 'pinned' parameter in do_lock_mount()

[Al Viro]

On Wed, Sep 24, 2025 at 07:36:11PM +0000, Kriish Sharma wrote:
> The kernel-doc comment for do_lock_mount() was missing a description
> for the 'pinned' parameter:
> 
>   Warning: fs/namespace.c:2772 function parameter 'pinned' not described
>   in 'do_lock_mount'
> 
> This patch adds a short description:
> 
>   @pinned: receives the pinned mountpoint
> 
> to fix the warning and improve documentation clarity.

Sigh...  There we go again...
	1.  It does not improve documentation clarity - it adds
a misleading line to an opaque chunk of text that does not match
what the function *does*.
	2.  In -next both the calling conventions and the comment
are both changed, hopefully making it more readable.
	3.  Essentially the same patch has already been posted and
discussed.

NAKed-by: Al Viro <viro@zeniv.linux.org.uk>

Re: [PATCH] fs: doc: describe 'pinned' parameter in do_lock_mount()

[Al Viro]

On Wed, Sep 24, 2025 at 09:57:30PM +0100, Al Viro wrote:
> On Wed, Sep 24, 2025 at 07:36:11PM +0000, Kriish Sharma wrote:
> > The kernel-doc comment for do_lock_mount() was missing a description
> > for the 'pinned' parameter:
> > 
> >   Warning: fs/namespace.c:2772 function parameter 'pinned' not described
> >   in 'do_lock_mount'
> > 
> > This patch adds a short description:
> > 
> >   @pinned: receives the pinned mountpoint
> > 
> > to fix the warning and improve documentation clarity.
> 
> Sigh...  There we go again...
> 	1.  It does not improve documentation clarity - it adds
> a misleading line to an opaque chunk of text that does not match
> what the function *does*.
> 	2.  In -next both the calling conventions and the comment
> are both changed, hopefully making it more readable.
> 	3.  Essentially the same patch has already been posted and
> discussed.
> 
> NAKed-by: Al Viro <viro@zeniv.linux.org.uk>

PS: as for the clarity, I'd like to point out that with your patch
applied nothing in the comments explains what is *done* to that
argument - it's not even mentioned there.  Incidentally, "receives"
normally implies an IN argument; this is an OUT one (function set the
environment for mounting something at given location and stores the
resulting context in caller-supplied structure).

Comment quality needs to be improved and these warnings actually
do catch some of the stale (and generally incomprehensible) ones.
Unfortunately, it's easy to fool the heuristics without doing
anything about the underlying problem, in effect hiding it.

Folks, please don't do that - this is not an improvement.  If you
spot something of that sort and want to take a pass at fixing it,
more power to you, but the main criteria here would be "does that
text make it easier to understand the function in question and/or
the rules for using it".  If it's genuinely hard to figure out,
don't hesitate to ask.