[PATCH] VFS: namei: fix __start_dirop() kernel-doc warnings

[PATCH] VFS: namei: fix __start_dirop() kernel-doc warnings

[Randy Dunlap]

Use the correct function name and add description for the @state
parameter to avoid these kernel-doc warnings:

Warning: fs/namei.c:2853 function parameter 'state' not described
 in '__start_dirop'
WARNING: fs/namei.c:2853 expecting prototype for start_dirop().
 Prototype was for __start_dirop() instead

Fixes: ff7c4ea11a05 ("VFS: add start_creating_killable() and start_removing_killable()")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: NeilBrown <neil@brown.name>
Cc: Christian Brauner <brauner@kernel.org>
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
Cc: Jan Kara <jack@suse.cz>
---
 fs/namei.c |    3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

--- linux-next-20251127.orig/fs/namei.c
+++ linux-next-20251127/fs/namei.c
@@ -2836,10 +2836,11 @@ static int filename_parentat(int dfd, st
 }
 
 /**
- * start_dirop - begin a create or remove dirop, performing locking and lookup
+ * __start_dirop - begin a create or remove dirop, performing locking and lookup
  * @parent:       the dentry of the parent in which the operation will occur
  * @name:         a qstr holding the name within that parent
  * @lookup_flags: intent and other lookup flags.
+ * @state:        target task state
  *
  * The lookup is performed and necessary locks are taken so that, on success,
  * the returned dentry can be operated on safely.

Re: [PATCH] VFS: namei: fix __start_dirop() kernel-doc warnings

[NeilBrown]

On Fri, 28 Nov 2025, Randy Dunlap wrote:
> Use the correct function name and add description for the @state
> parameter to avoid these kernel-doc warnings:
> 
> Warning: fs/namei.c:2853 function parameter 'state' not described
>  in '__start_dirop'
> WARNING: fs/namei.c:2853 expecting prototype for start_dirop().
>  Prototype was for __start_dirop() instead
> 
> Fixes: ff7c4ea11a05 ("VFS: add start_creating_killable() and start_removing_killable()")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: NeilBrown <neil@brown.name>
> Cc: Christian Brauner <brauner@kernel.org>
> Cc: Alexander Viro <viro@zeniv.linux.org.uk>
> Cc: Jan Kara <jack@suse.cz>
> ---
>  fs/namei.c |    3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> --- linux-next-20251127.orig/fs/namei.c
> +++ linux-next-20251127/fs/namei.c
> @@ -2836,10 +2836,11 @@ static int filename_parentat(int dfd, st
>  }
>  
>  /**
> - * start_dirop - begin a create or remove dirop, performing locking and lookup
> + * __start_dirop - begin a create or remove dirop, performing locking and lookup
>   * @parent:       the dentry of the parent in which the operation will occur
>   * @name:         a qstr holding the name within that parent
>   * @lookup_flags: intent and other lookup flags.
> + * @state:        target task state
>   *
>   * The lookup is performed and necessary locks are taken so that, on success,
>   * the returned dentry can be operated on safely.
> 

Thanks - but I would rather the doc comment were moved down to be
immediately before start_dirop().

If we were to document __start_dirop (as well?) we would need to
actually say what @state is used for.

Thanks,
NeilBrown

Re: [PATCH] VFS: namei: fix __start_dirop() kernel-doc warnings

[Randy Dunlap]

On 11/27/25 5:11 PM, NeilBrown wrote:
> On Fri, 28 Nov 2025, Randy Dunlap wrote:
>> Use the correct function name and add description for the @state
>> parameter to avoid these kernel-doc warnings:
>>
>> Warning: fs/namei.c:2853 function parameter 'state' not described
>>  in '__start_dirop'
>> WARNING: fs/namei.c:2853 expecting prototype for start_dirop().
>>  Prototype was for __start_dirop() instead
>>
>> Fixes: ff7c4ea11a05 ("VFS: add start_creating_killable() and start_removing_killable()")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>> Cc: NeilBrown <neil@brown.name>
>> Cc: Christian Brauner <brauner@kernel.org>
>> Cc: Alexander Viro <viro@zeniv.linux.org.uk>
>> Cc: Jan Kara <jack@suse.cz>
>> ---
>>  fs/namei.c |    3 ++-
>>  1 file changed, 2 insertions(+), 1 deletion(-)
>>
>> --- linux-next-20251127.orig/fs/namei.c
>> +++ linux-next-20251127/fs/namei.c
>> @@ -2836,10 +2836,11 @@ static int filename_parentat(int dfd, st
>>  }
>>  
>>  /**
>> - * start_dirop - begin a create or remove dirop, performing locking and lookup
>> + * __start_dirop - begin a create or remove dirop, performing locking and lookup
>>   * @parent:       the dentry of the parent in which the operation will occur
>>   * @name:         a qstr holding the name within that parent
>>   * @lookup_flags: intent and other lookup flags.
>> + * @state:        target task state
>>   *
>>   * The lookup is performed and necessary locks are taken so that, on success,
>>   * the returned dentry can be operated on safely.
>>
> 
> Thanks - but I would rather the doc comment were moved down to be
> immediately before start_dirop().

Sounds good.

> If we were to document __start_dirop (as well?) we would need to
> actually say what @state is used for.
-- 
~Randy