[PATCH 0/5] kernel-doc fixes to latest fs changes

this patchset was motivated by new warnings with make htmldocs appearing on
linux-next in the last week.

Please apply this on top of your latest work in fs on top of the mount user
namespace refactoring, cf. the commits referred in the individual commit
messages.


Lukas Bulwahn (5):
  fs: turn some comments into kernel-doc
  fs: update kernel-doc for vfs_rename()
  fs: update kernel-doc for may_create_in_sticky()
  fs: update kernel-doc for vfs_tmpfile()
  fs: update kernel-doc for new mnt_userns argument

 fs/libfs.c         |  1 +
 fs/namei.c         | 13 ++-----------
 fs/xattr.c         |  2 ++
 include/linux/fs.h | 17 ++++++++++++++---
 4 files changed, 19 insertions(+), 14 deletions(-)

-- 
2.17.1

Commit ba73d98745be ("namei: handle idmapped mounts in may_*() helpers")
refactors may_create_in_sticky(), adds kernel-doc for the new argument,
but missed to drop the kernel-doc for the removed arguments.

Hence, make htmldocs warns on ./fs/namei.c:1149:

  warning: Excess function parameter 'dir_mode' description in 'may_create_in_sticky'
  warning: Excess function parameter 'dir_uid' description in 'may_create_in_sticky'

Drop removed arguments from kernel-doc of may_create_in_sticky().

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
 fs/namei.c | 2 --
 1 file changed, 2 deletions(-)

diff --git a/fs/namei.c b/fs/namei.c
index 98ea56ebcaf0..64a841dfbb3e 100644
--- a/fs/namei.c
+++ b/fs/namei.c

@@ -1121,8 +1121,6 @@ int may_linkat(struct user_namespace *mnt_userns, struct path *link)
  *			  should be allowed, or not, on files that already
  *			  exist.
  * @mnt_userns:	user namespace of the mount the inode was found from
- * @dir_mode: mode bits of directory
- * @dir_uid: owner of directory
  * @inode: the inode of the file to open
  *
  * Block an O_CREAT open of a FIFO (or a regular file) when:

-- 
2.17.1

Commit 6521f8917082 ("namei: prepare for idmapped mounts") adds kernel-doc
for vfs_tmpfile(), but with a small typo in one argument name.

Hence, make htmldocs warns on ./fs/namei.c:3396:

  warning: Function parameter or member 'open_flag' not described in 'vfs_tmpfile'
  warning: Excess function parameter 'open_flags' description in 'vfs_tmpfile'

Fix this typo in kernel-doc of vfs_tmpfile().

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
 fs/namei.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/fs/namei.c b/fs/namei.c
index 64a841dfbb3e..9f7d260ffb4b 100644
--- a/fs/namei.c
+++ b/fs/namei.c

@@ -3379,7 +3379,7 @@ static int do_open(struct nameidata *nd,
  * @mnt_userns:	user namespace of the mount the inode was found from
  * @dentry:	pointer to dentry of the base directory
  * @mode:	mode of the new tmpfile
- * @open_flags:	flags
+ * @open_flag:	flags
  *
  * Create a temporary file.
  *

-- 
2.17.1

Commit 9fe61450972d ("namei: introduce struct renamedata") introduces a
new struct for vfs_rename() and makes the vfs_rename() kernel-doc argument
description out of sync.

Move the description of arguments for vfs_rename() to a new kernel-doc for
the struct renamedata to make these descriptions checkable against the
actual implementation.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
 fs/namei.c         |  9 +--------
 include/linux/fs.h | 11 +++++++++++
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/fs/namei.c b/fs/namei.c
index f131d3efec63..98ea56ebcaf0 100644
--- a/fs/namei.c
+++ b/fs/namei.c

@@ -4406,14 +4406,7 @@ SYSCALL_DEFINE2(link, const char __user *, oldname, const char __user *, newname
 
 /**
  * vfs_rename - rename a filesystem object
- * @old_mnt_userns:	old user namespace of the mount the inode was found from
- * @old_dir:		parent of source
- * @old_dentry:		source
- * @new_mnt_userns:	new user namespace of the mount the inode was found from
- * @new_dir:		parent of destination
- * @new_dentry:		destination
- * @delegated_inode:	returns an inode needing a delegation break
- * @flags:		rename flags
+ * @rd: struct with all information required for renaming
  *
  * The caller must hold multiple mutexes--see lock_rename()).
  *

diff --git a/include/linux/fs.h b/include/linux/fs.h
index 04b6b142dfcf..52b6d9e34b92 100644
--- a/include/linux/fs.h
+++ b/include/linux/fs.h

@@ -1782,6 +1782,17 @@ int vfs_rmdir(struct user_namespace *, struct inode *, struct dentry *);
 int vfs_unlink(struct user_namespace *, struct inode *, struct dentry *,
 	       struct inode **);
 
+/**
+ * struct renamedata - contains all information required for renaming
+ * @old_mnt_userns:    old user namespace of the mount the inode was found from
+ * @old_dir:           parent of source
+ * @old_dentry:                source
+ * @new_mnt_userns:    new user namespace of the mount the inode was found from
+ * @new_dir:           parent of destination
+ * @new_dentry:                destination
+ * @delegated_inode:   returns an inode needing a delegation break
+ * @flags:             rename flags
+ */
 struct renamedata {
 	struct user_namespace *old_mnt_userns;
 	struct inode *old_dir;

-- 
2.17.1

Commit 549c7297717c ("fs: make helpers idmap mount aware") and commit
c7c7a1a18af4 ("xattr: handle idmapped mounts") refactor the inode methods
with mount-user-namespace arguments, but did not adjust the kernel-doc of
some functions.

Hence, make htmldocs warns:

  ./fs/libfs.c:498: warning: Function parameter or member 'mnt_userns' not described in 'simple_setattr'
  ./fs/xattr.c:257: warning: Function parameter or member 'mnt_userns' not described in '__vfs_setxattr_locked'
  ./fs/xattr.c:485: warning: Function parameter or member 'mnt_userns' not described in '__vfs_removexattr_locked'

Copy the existing kernel-doc description for that new argument from
__vfs_setxattr_noperm() to the other functions as well.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
 fs/libfs.c | 1 +
 fs/xattr.c | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/fs/libfs.c b/fs/libfs.c
index e2de5401abca..61c684014392 100644
--- a/fs/libfs.c
+++ b/fs/libfs.c

@@ -481,6 +481,7 @@ EXPORT_SYMBOL(simple_rename);
 
 /**
  * simple_setattr - setattr for simple filesystem
+ * @mnt_userns: user namespace of the mount the inode was found from
  * @dentry: dentry
  * @iattr: iattr structure
  *

diff --git a/fs/xattr.c b/fs/xattr.c
index b3444e06cded..57f47f0caf22 100644
--- a/fs/xattr.c
+++ b/fs/xattr.c

@@ -242,6 +242,7 @@ int __vfs_setxattr_noperm(struct user_namespace *mnt_userns,
  * __vfs_setxattr_locked - set an extended attribute while holding the inode
  * lock
  *
+ *  @mnt_userns: user namespace of the mount the inode was found from
  *  @dentry: object to perform setxattr on
  *  @name: xattr name to set
  *  @value: value to set @name to

@@ -473,6 +474,7 @@ EXPORT_SYMBOL(__vfs_removexattr);
  * __vfs_removexattr_locked - set an extended attribute while holding the inode
  * lock
  *
+ *  @mnt_userns: user namespace of the mount the inode was found from
  *  @dentry: object to perform setxattr on
  *  @name: name of xattr to remove
  *  @delegated_inode: on return, will contain an inode pointer that

-- 
2.17.1

While reviewing ./include/linux/fs.h, I noticed that three comments can
actually be turned into kernel-doc comments. This allows to check the
consistency between the descriptions and the functions' signatures in
case they may change in the future.

A quick validation with the consistency check:

  ./scripts/kernel-doc -none include/linux/fs.h

currently reports no issues in this file.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
 include/linux/fs.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/linux/fs.h b/include/linux/fs.h
index 3482146b11b0..04b6b142dfcf 100644
--- a/include/linux/fs.h
+++ b/include/linux/fs.h

@@ -1739,7 +1739,7 @@ static inline void sb_start_pagefault(struct super_block *sb)
 	__sb_start_write(sb, SB_FREEZE_PAGEFAULT);
 }
 
-/*
+/**
  * sb_start_intwrite - get write access to a superblock for internal fs purposes
  * @sb: the super we write to
  *

@@ -3162,7 +3162,7 @@ static inline ssize_t blockdev_direct_IO(struct kiocb *iocb,
 
 void inode_dio_wait(struct inode *inode);
 
-/*
+/**
  * inode_dio_begin - signal start of a direct I/O requests
  * @inode: inode the direct I/O happens on
  *

@@ -3174,7 +3174,7 @@ static inline void inode_dio_begin(struct inode *inode)
 	atomic_inc(&inode->i_dio_count);
 }
 
-/*
+/**
  * inode_dio_end - signal finish of a direct I/O requests
  * @inode: inode the direct I/O happens on
  *

-- 
2.17.1

On Thu, Feb 04, 2021 at 07:00:54PM +0100, Lukas Bulwahn wrote:

this patchset was motivated by new warnings with make htmldocs appearing on
linux-next in the last week.

Please apply this on top of your latest work in fs on top of the mount user
namespace refactoring, cf. the commits referred in the individual commit
messages.


Lukas Bulwahn (5):
  fs: turn some comments into kernel-doc
  fs: update kernel-doc for vfs_rename()
  fs: update kernel-doc for may_create_in_sticky()
  fs: update kernel-doc for vfs_tmpfile()
  fs: update kernel-doc for new mnt_userns argument

 fs/libfs.c         |  1 +
 fs/namei.c         | 13 ++-----------
 fs/xattr.c         |  2 ++
 include/linux/fs.h | 17 ++++++++++++++---
 4 files changed, 19 insertions(+), 14 deletions(-)

Thanks for fixing this up, Lukas. Randy has fixed some of my missing
comment updates as well so we only needed

  fs: turn some comments into kernel-doc
  fs: update kernel-doc for vfs_rename()

Christian