diff mbox series

cifs: remove various function description warnings

Message ID CAH2r5mueeQZHmzffOT=5z7FyENgK+0J_gjTuEVWRj=p1qe-gTQ@mail.gmail.com (mailing list archive)
State New, archived
Headers show
Series cifs: remove various function description warnings | expand

Commit Message

Steve French Dec. 12, 2020, 6:18 p.m. UTC
When compiling with W=1 I noticed various functions that
did not follow proper style in describing (in the comments)
the parameters passed in to the function. For example:

fs/cifs/inode.c:2236: warning: Function parameter or member 'mode' not
described in 'cifs_wait_bit_killable'

I did not address the style warnings in two of the six files
(connect.c and misc.c) in order to reduce risk of merge
conflict with pending patches. We can update those later.

Signed-off-by: Steve French <stfrench@microsoft.com>
---
 fs/cifs/cifs_dfs_ref.c |  1 +
 fs/cifs/file.c         |  9 +++++++--
 fs/cifs/inode.c        | 16 +++++++++++-----
 fs/cifs/smb2misc.c     |  4 ++++
 4 files changed, 23 insertions(+), 7 deletions(-)

 smb311_update_preauth_hash(struct cifs_ses *ses, struct kvec *iov, int nvec)
diff mbox series

Patch

diff --git a/fs/cifs/cifs_dfs_ref.c b/fs/cifs/cifs_dfs_ref.c
index 6f7187b90fda..e4c6ae47a796 100644
--- a/fs/cifs/cifs_dfs_ref.c
+++ b/fs/cifs/cifs_dfs_ref.c
@@ -254,6 +254,7 @@  char *cifs_compose_mount_options(const char *sb_mountdata,
  * to perform failover in case we failed to connect to the first target in the
  * referral.
  *
+ * @mntpt: directory entry for the path we are trying to automount
  * @cifs_sb: parent/root superblock
  * @fullpath: full path in UNC format
  */
diff --git a/fs/cifs/file.c b/fs/cifs/file.c
index be46fab4c96d..29176a56229f 100644
--- a/fs/cifs/file.c
+++ b/fs/cifs/file.c
@@ -416,6 +416,8 @@  static void cifsFileInfo_put_work(struct work_struct *work)
  * cifsFileInfo_put - release a reference of file priv data
  *
  * Always potentially wait for oplock handler. See _cifsFileInfo_put().
+ *
+ * @cifs_file: cifs/smb3 specific info (eg refcounts) for an open file
  */
 void cifsFileInfo_put(struct cifsFileInfo *cifs_file)
 {
@@ -431,8 +433,11 @@  void cifsFileInfo_put(struct cifsFileInfo *cifs_file)
  *
  * If @wait_for_oplock_handler is true and we are releasing the last
  * reference, wait for any running oplock break handler of the file
- * and cancel any pending one. If calling this function from the
- * oplock break handler, you need to pass false.
+ * and cancel any pending one.
+ *
+ * @cifs_file: cifs/smb3 specific info (eg refcounts) for an open file
+ * @wait_oplock_handler: must be false if called from oplock_break_handler
+ * @offload: not offloaded on close and oplock breaks
  *
  */
 void _cifsFileInfo_put(struct cifsFileInfo *cifs_file,
diff --git a/fs/cifs/inode.c b/fs/cifs/inode.c
index 8debd4c18faf..2a5c4fef9b59 100644
--- a/fs/cifs/inode.c
+++ b/fs/cifs/inode.c
@@ -804,11 +804,15 @@  static __u64 simple_hashstr(const char *str)
  * cifs_backup_query_path_info - SMB1 fallback code to get ino
  *
  * Fallback code to get file metadata when we don't have access to
- * @full_path (EACCES) and have backup creds.
+ * full_path (EACCES) and have backup creds.
  *When compiling with W=1 I noticed various functions that
did not follow proper style in describing (in the comments)
the parameters passed in to the function. For example:

fs/cifs/inode.c:2236: warning: Function parameter or member 'mode' not
described in 'cifs_wait_bit_killable'

I did not address the style warnings in two of the six files
(connect.c and misc.c) in order to reduce risk of merge
conflict with pending patches. We can update those later.

Signed-off-by: Steve French <stfrench@microsoft.com>
---
 fs/cifs/cifs_dfs_ref.c |  1 +
 fs/cifs/file.c         |  9 +++++++--
 fs/cifs/inode.c        | 16 +++++++++++-----
 fs/cifs/smb2misc.c     |  4 ++++
 4 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/fs/cifs/cifs_dfs_ref.c b/fs/cifs/cifs_dfs_ref.c
index 6f7187b90fda..e4c6ae47a796 100644
--- a/fs/cifs/cifs_dfs_ref.c
+++ b/fs/cifs/cifs_dfs_ref.c
@@ -254,6 +254,7 @@  char *cifs_compose_mount_options(const char *sb_mountdata,
  * to perform failover in case we failed to connect to the first target in the
  * referral.
  *
+ * @mntpt: directory entry for the path we are trying to automount
  * @cifs_sb: parent/root superblock
  * @fullpath: full path in UNC format
  */
diff --git a/fs/cifs/file.c b/fs/cifs/file.c
index be46fab4c96d..29176a56229f 100644
--- a/fs/cifs/file.c
+++ b/fs/cifs/file.c
@@ -416,6 +416,8 @@  static void cifsFileInfo_put_work(struct work_struct *work)
  * cifsFileInfo_put - release a reference of file priv data
  *
  * Always potentially wait for oplock handler. See _cifsFileInfo_put().
+ *
+ * @cifs_file: cifs/smb3 specific info (eg refcounts) for an open file
  */
 void cifsFileInfo_put(struct cifsFileInfo *cifs_file)
 {
@@ -431,8 +433,11 @@  void cifsFileInfo_put(struct cifsFileInfo *cifs_file)
  *
  * If @wait_for_oplock_handler is true and we are releasing the last
  * reference, wait for any running oplock break handler of the file
- * and cancel any pending one. If calling this function from the
- * oplock break handler, you need to pass false.
+ * and cancel any pending one.
+ *
+ * @cifs_file: cifs/smb3 specific info (eg refcounts) for an open file
+ * @wait_oplock_handler: must be false if called from oplock_break_handler
+ * @offload: not offloaded on close and oplock breaks
  *
  */
 void _cifsFileInfo_put(struct cifsFileInfo *cifs_file,
diff --git a/fs/cifs/inode.c b/fs/cifs/inode.c
index 8debd4c18faf..2a5c4fef9b59 100644
--- a/fs/cifs/inode.c
+++ b/fs/cifs/inode.c
@@ -804,11 +804,15 @@  static __u64 simple_hashstr(const char *str)
  * cifs_backup_query_path_info - SMB1 fallback code to get ino
  *
  * Fallback code to get file metadata when we don't have access to
- * @full_path (EACCES) and have backup creds.
+ * full_path (EACCES) and have backup creds.
  *
- * @data will be set to search info result buffer
- * @resp_buf will be set to cifs resp buf and needs to be freed with
- * cifs_buf_release() when done with @data.
+ * @xid: transaction id used to identify original request in logs
+ * @tcon: information about the server share we have mounted
+ * @sb: the superblock stores info such as disk space available
+ * @full_path: name of the file we are getting the metadata for
+ * @resp_buf: will be set to cifs resp buf and needs to be freed with
+ * cifs_buf_release() when done with @data
+ * @data: will be set to search info result buffer
  */
 static int
 cifs_backup_query_path_info(int xid,
@@ -2229,7 +2233,9 @@  cifs_invalidate_mapping(struct inode *inode)

 /**
  * cifs_wait_bit_killable - helper for functions that are sleeping on bit locks
- * @word: long word containing the bit lock
+ *
+ * @key: currently unused
+ * @mode: the task state to sleep in
  */
 static int
 cifs_wait_bit_killable(struct wait_bit_key *key, int mode)
diff --git a/fs/cifs/smb2misc.c b/fs/cifs/smb2misc.c
index a82008a7cffb..99a4e40a2532 100644
--- a/fs/cifs/smb2misc.c
+++ b/fs/cifs/smb2misc.c
@@ -876,6 +876,10 @@  smb2_handle_cancelled_mid(char *buffer, struct
TCP_Server_Info *server)
  *
  * Assumes @iov does not contain the rfc1002 length and iov[0] has the
  * SMB2 header.
+ *
+ * @ses: server session structure
+ * @iov: array containing the SMB request we will send to the server
+ * @nvec: number of array entries for the iov
  */
 int
 smb311_update_preauth_hash(struct cifs_ses *ses, struct kvec *iov, int nvec)
- * @data will be set to search info result buffer
- * @resp_buf will be set to cifs resp buf and needs to be freed with
- * cifs_buf_release() when done with @data.
+ * @xid: transaction id used to identify original request in logs
+ * @tcon: information about the server share we have mounted
+ * @sb: the superblock stores info such as disk space available
+ * @full_path: name of the file we are getting the metadata for
+ * @resp_buf: will be set to cifs resp buf and needs to be freed with
+ * cifs_buf_release() when done with @data
+ * @data: will be set to search info result buffer
  */
 static int
 cifs_backup_query_path_info(int xid,
@@ -2229,7 +2233,9 @@  cifs_invalidate_mapping(struct inode *inode)

 /**
  * cifs_wait_bit_killable - helper for functions that are sleeping on bit locks
- * @word: long word containing the bit lock
+ *
+ * @key: currently unused
+ * @mode: the task state to sleep in
  */
 static int
 cifs_wait_bit_killable(struct wait_bit_key *key, int mode)
diff --git a/fs/cifs/smb2misc.c b/fs/cifs/smb2misc.c
index a82008a7cffb..99a4e40a2532 100644
--- a/fs/cifs/smb2misc.c
+++ b/fs/cifs/smb2misc.c
@@ -876,6 +876,10 @@  smb2_handle_cancelled_mid(char *buffer, struct
TCP_Server_Info *server)
  *
  * Assumes @iov does not contain the rfc1002 length and iov[0] has the
  * SMB2 header.
+ *
+ * @ses: server session structure
+ * @iov: array containing the SMB request we will send to the server
+ * @nvec: number of array entries for the iov
  */
 int