[PATCH] fs: Eliminate compilation warnings for misc

[PATCH] fs: Eliminate compilation warnings for misc

[Tianjia Zhang]

Eliminate the following clang compilation warnings by adding or
fixing function comment:

  fs/file.c:655: warning: Function parameter or member 'fdt' not described in 'last_fd'
  fs/file.c:655: warning: Excess function parameter 'cur_fds' description in 'last_fd'
  fs/file.c:703: warning: Function parameter or member 'flags' not described in '__close_range'

  fs/fs_context.c:202: warning: Function parameter or member 'fc' not described in 'generic_parse_monolithic'
  fs/fs_context.c:202: warning: Excess function parameter 'ctx' description in 'generic_parse_monolithic'
  fs/fs_context.c:386: warning: Function parameter or member 'log' not described in 'logfc'
  fs/fs_context.c:386: warning: Function parameter or member 'prefix' not described in 'logfc'
  fs/fs_context.c:386: warning: Function parameter or member 'level' not described in 'logfc'
  fs/fs_context.c:386: warning: Excess function parameter 'fc' description in 'logfc'

  fs/namei.c:1044: warning: Function parameter or member 'inode' not described in 'may_follow_link'

  fs/read_write.c:88: warning: Function parameter or member 'maxsize' not described in 'generic_file_llseek_size'
  fs/read_write.c:88: warning: Excess function parameter 'size' description in 'generic_file_llseek_size'

Signed-off-by: Tianjia Zhang <tianjia.zhang@linux.alibaba.com>
---
 fs/file.c       | 3 ++-
 fs/fs_context.c | 6 ++++--
 fs/namei.c      | 1 +
 fs/read_write.c | 2 +-
 4 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/fs/file.c b/fs/file.c
index 8627dacfc424..ab3b635b0c86 100644
--- a/fs/file.c
+++ b/fs/file.c
@@ -645,7 +645,7 @@ EXPORT_SYMBOL(close_fd); /* for ksys_close() */
 
 /**
  * last_fd - return last valid index into fd table
- * @cur_fds: files struct
+ * @fdt: fdtable struct
  *
  * Context: Either rcu read lock or files_lock must be held.
  *
@@ -695,6 +695,7 @@ static inline void __range_close(struct files_struct *cur_fds, unsigned int fd,
  *
  * @fd:     starting file descriptor to close
  * @max_fd: last file descriptor to close
+ * @flags:  close range flags
  *
  * This closes a range of file descriptors. All file descriptors
  * from @fd up to and including @max_fd are closed.
diff --git a/fs/fs_context.c b/fs/fs_context.c
index b7e43a780a62..e94fb7f19d3f 100644
--- a/fs/fs_context.c
+++ b/fs/fs_context.c
@@ -189,7 +189,7 @@ EXPORT_SYMBOL(vfs_parse_fs_string);
 
 /**
  * generic_parse_monolithic - Parse key[=val][,key[=val]]* mount data
- * @ctx: The superblock configuration to fill in.
+ * @fc: filesystem context
  * @data: The data to parse
  *
  * Parse a blob of data that's in key[=val][,key[=val]]* form.  This can be
@@ -379,7 +379,9 @@ EXPORT_SYMBOL(vfs_dup_fs_context);
 
 /**
  * logfc - Log a message to a filesystem context
- * @fc: The filesystem context to log to.
+ * @log: The filesystem context to log to.
+ * @prefix: The log prefix.
+ * @level: The log level.
  * @fmt: The format of the buffer.
  */
 void logfc(struct fc_log *log, const char *prefix, char level, const char *fmt, ...)
diff --git a/fs/namei.c b/fs/namei.c
index 1f9d2187c765..3bc73b4f39c9 100644
--- a/fs/namei.c
+++ b/fs/namei.c
@@ -1028,6 +1028,7 @@ int sysctl_protected_regular __read_mostly;
 /**
  * may_follow_link - Check symlink following for unsafe situations
  * @nd: nameidata pathwalk data
+ * @inode: inode to check
  *
  * In the case of the sysctl_protected_symlinks sysctl being enabled,
  * CAP_DAC_OVERRIDE needs to be specifically ignored if the symlink is
diff --git a/fs/read_write.c b/fs/read_write.c
index 0074afa7ecb3..d7b0f8528930 100644
--- a/fs/read_write.c
+++ b/fs/read_write.c
@@ -71,7 +71,7 @@ EXPORT_SYMBOL(vfs_setpos);
  * @file:	file structure to seek on
  * @offset:	file offset to seek to
  * @whence:	type of seek
- * @size:	max size of this file in file system
+ * @maxsize:	max size of this file in file system
  * @eof:	offset used for SEEK_END position
  *
  * This is a variant of generic_file_llseek that allows passing in a custom
-- 
2.32.0

Re: [PATCH] fs: Eliminate compilation warnings for misc

[Matthew Wilcox]

On Tue, Nov 16, 2021 at 04:06:11PM +0800, Tianjia Zhang wrote:
> Eliminate the following clang compilation warnings by adding or
> fixing function comment:

These warnings have nothing to do with clang.  They're produced by
scripts/kernel-doc:

                if (show_warnings($type, $declaration_name) && $param !~ /\./) {
                        print STDERR
                              "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
                        ++$warnings;
                }

They show up in any W=1 build (which tells you that people are not
checking their patches with W=1)

> +++ b/fs/file.c
> @@ -645,7 +645,7 @@ EXPORT_SYMBOL(close_fd); /* for ksys_close() */
>  
>  /**
>   * last_fd - return last valid index into fd table
> - * @cur_fds: files struct
> + * @fdt: fdtable struct

I don't think the word 'struct' there really conveys any meaning.

Re: [PATCH] fs: Eliminate compilation warnings for misc

[Randy Dunlap]

On 11/16/21 12:06 AM, Tianjia Zhang wrote:
> Eliminate the following clang compilation warnings by adding or
> fixing function comment:

These are from clang?  They all appear to be from scripts/kernel-doc.

Can someone please clarify?

thanks.

>    fs/file.c:655: warning: Function parameter or member 'fdt' not described in 'last_fd'
>    fs/file.c:655: warning: Excess function parameter 'cur_fds' description in 'last_fd'
>    fs/file.c:703: warning: Function parameter or member 'flags' not described in '__close_range'
> 
>    fs/fs_context.c:202: warning: Function parameter or member 'fc' not described in 'generic_parse_monolithic'
>    fs/fs_context.c:202: warning: Excess function parameter 'ctx' description in 'generic_parse_monolithic'
>    fs/fs_context.c:386: warning: Function parameter or member 'log' not described in 'logfc'
>    fs/fs_context.c:386: warning: Function parameter or member 'prefix' not described in 'logfc'
>    fs/fs_context.c:386: warning: Function parameter or member 'level' not described in 'logfc'
>    fs/fs_context.c:386: warning: Excess function parameter 'fc' description in 'logfc'
> 
>    fs/namei.c:1044: warning: Function parameter or member 'inode' not described in 'may_follow_link'
> 
>    fs/read_write.c:88: warning: Function parameter or member 'maxsize' not described in 'generic_file_llseek_size'
>    fs/read_write.c:88: warning: Excess function parameter 'size' description in 'generic_file_llseek_size'
> 
> Signed-off-by: Tianjia Zhang <tianjia.zhang@linux.alibaba.com>
> ---
>   fs/file.c       | 3 ++-
>   fs/fs_context.c | 6 ++++--
>   fs/namei.c      | 1 +
>   fs/read_write.c | 2 +-
>   4 files changed, 8 insertions(+), 4 deletions(-)
> 
> diff --git a/fs/file.c b/fs/file.c
> index 8627dacfc424..ab3b635b0c86 100644
> --- a/fs/file.c
> +++ b/fs/file.c
> @@ -645,7 +645,7 @@ EXPORT_SYMBOL(close_fd); /* for ksys_close() */
>   
>   /**
>    * last_fd - return last valid index into fd table
> - * @cur_fds: files struct
> + * @fdt: fdtable struct
>    *
>    * Context: Either rcu read lock or files_lock must be held.
>    *
> @@ -695,6 +695,7 @@ static inline void __range_close(struct files_struct *cur_fds, unsigned int fd,
>    *
>    * @fd:     starting file descriptor to close
>    * @max_fd: last file descriptor to close
> + * @flags:  close range flags
>    *
>    * This closes a range of file descriptors. All file descriptors
>    * from @fd up to and including @max_fd are closed.
> diff --git a/fs/fs_context.c b/fs/fs_context.c
> index b7e43a780a62..e94fb7f19d3f 100644
> --- a/fs/fs_context.c
> +++ b/fs/fs_context.c
> @@ -189,7 +189,7 @@ EXPORT_SYMBOL(vfs_parse_fs_string);
>   
>   /**
>    * generic_parse_monolithic - Parse key[=val][,key[=val]]* mount data
> - * @ctx: The superblock configuration to fill in.
> + * @fc: filesystem context
>    * @data: The data to parse
>    *
>    * Parse a blob of data that's in key[=val][,key[=val]]* form.  This can be
> @@ -379,7 +379,9 @@ EXPORT_SYMBOL(vfs_dup_fs_context);
>   
>   /**
>    * logfc - Log a message to a filesystem context
> - * @fc: The filesystem context to log to.
> + * @log: The filesystem context to log to.
> + * @prefix: The log prefix.
> + * @level: The log level.
>    * @fmt: The format of the buffer.
>    */
>   void logfc(struct fc_log *log, const char *prefix, char level, const char *fmt, ...)
> diff --git a/fs/namei.c b/fs/namei.c
> index 1f9d2187c765..3bc73b4f39c9 100644
> --- a/fs/namei.c
> +++ b/fs/namei.c
> @@ -1028,6 +1028,7 @@ int sysctl_protected_regular __read_mostly;
>   /**
>    * may_follow_link - Check symlink following for unsafe situations
>    * @nd: nameidata pathwalk data
> + * @inode: inode to check
>    *
>    * In the case of the sysctl_protected_symlinks sysctl being enabled,
>    * CAP_DAC_OVERRIDE needs to be specifically ignored if the symlink is
> diff --git a/fs/read_write.c b/fs/read_write.c
> index 0074afa7ecb3..d7b0f8528930 100644
> --- a/fs/read_write.c
> +++ b/fs/read_write.c
> @@ -71,7 +71,7 @@ EXPORT_SYMBOL(vfs_setpos);
>    * @file:	file structure to seek on
>    * @offset:	file offset to seek to
>    * @whence:	type of seek
> - * @size:	max size of this file in file system
> + * @maxsize:	max size of this file in file system
>    * @eof:	offset used for SEEK_END position
>    *
>    * This is a variant of generic_file_llseek that allows passing in a custom
> 


-- 
~Randy

Re: [PATCH] fs: Eliminate compilation warnings for misc

[Tianjia Zhang]

Hi Matthew,

On 11/17/21 1:19 AM, Matthew Wilcox wrote:
> On Tue, Nov 16, 2021 at 04:06:11PM +0800, Tianjia Zhang wrote:
>> Eliminate the following clang compilation warnings by adding or
>> fixing function comment:
> 
> These warnings have nothing to do with clang.  They're produced by
> scripts/kernel-doc:
> 
>                  if (show_warnings($type, $declaration_name) && $param !~ /\./) {
>                          print STDERR
>                                "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
>                          ++$warnings;
>                  }
> 
> They show up in any W=1 build (which tells you that people are not
> checking their patches with W=1)
> 

Yes, there will be this warning when compiling with W=1.

>> +++ b/fs/file.c
>> @@ -645,7 +645,7 @@ EXPORT_SYMBOL(close_fd); /* for ksys_close() */
>>   
>>   /**
>>    * last_fd - return last valid index into fd table
>> - * @cur_fds: files struct
>> + * @fdt: fdtable struct
> 
> I don't think the word 'struct' there really conveys any meaning.
> 
I think this is already a primitive, or is there any better suggestion?

Kind regards,
Tianjia

Re: [PATCH] fs: Eliminate compilation warnings for misc

[Tianjia Zhang]

Hi Randy,

On 11/17/21 7:00 AM, Randy Dunlap wrote:
> On 11/16/21 12:06 AM, Tianjia Zhang wrote:
>> Eliminate the following clang compilation warnings by adding or
>> fixing function comment:
> 
> These are from clang?  They all appear to be from scripts/kernel-doc.
> 
> Can someone please clarify?
> 
> thanks.

Yes, compile with W=1, clang will report this warning.

Kind regards,
Tianjia

Re: [PATCH] fs: Eliminate compilation warnings for misc

[Matthew Wilcox]

On Mon, Nov 29, 2021 at 09:06:09PM +0800, Tianjia Zhang wrote:
> Hi Randy,
> 
> On 11/17/21 7:00 AM, Randy Dunlap wrote:
> > On 11/16/21 12:06 AM, Tianjia Zhang wrote:
> > > Eliminate the following clang compilation warnings by adding or
> > > fixing function comment:
> > 
> > These are from clang?  They all appear to be from scripts/kernel-doc.
> > 
> > Can someone please clarify?
> > 
> > thanks.
> 
> Yes, compile with W=1, clang will report this warning.

No, clang has nothing to do with it.  The warnings are from kernel-doc,
not clang.  Nor gcc.

Re: [PATCH] fs: Eliminate compilation warnings for misc

[Tianjia Zhang]

Hi Matthew,

On 11/29/21 9:19 PM, Matthew Wilcox wrote:
> On Mon, Nov 29, 2021 at 09:06:09PM +0800, Tianjia Zhang wrote:
>> Hi Randy,
>>
>> On 11/17/21 7:00 AM, Randy Dunlap wrote:
>>> On 11/16/21 12:06 AM, Tianjia Zhang wrote:
>>>> Eliminate the following clang compilation warnings by adding or
>>>> fixing function comment:
>>>
>>> These are from clang?  They all appear to be from scripts/kernel-doc.
>>>
>>> Can someone please clarify?
>>>
>>> thanks.
>>
>> Yes, compile with W=1, clang will report this warning.
> 
> No, clang has nothing to do with it.  The warnings are from kernel-doc,
> not clang.  Nor gcc.
> 

I was negligent, you are right. Thanks for pointing it out.

Best regards,
Tianjia