* [PATCH 1/5] fs: turn some comments into kernel-doc
2021-02-04 18:00 [PATCH 0/5] kernel-doc fixes to latest fs changes Lukas Bulwahn
@ 2021-02-04 18:00 ` Lukas Bulwahn
2021-02-04 18:00 ` [PATCH 2/5] fs: update kernel-doc for vfs_rename() Lukas Bulwahn
` (4 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Lukas Bulwahn @ 2021-02-04 18:00 UTC (permalink / raw)
To: Christian Brauner, linux-fsdevel
Cc: Alexander Viro, Mauro Carvalho Chehab, linux-doc,
kernel-janitors, linux-kernel, Lukas Bulwahn
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 2/5] fs: update kernel-doc for vfs_rename()
2021-02-04 18:00 [PATCH 0/5] kernel-doc fixes to latest fs changes Lukas Bulwahn
2021-02-04 18:00 ` [PATCH 1/5] fs: turn some comments into kernel-doc Lukas Bulwahn
@ 2021-02-04 18:00 ` Lukas Bulwahn
2021-02-04 18:00 ` [PATCH 3/5] fs: update kernel-doc for may_create_in_sticky() Lukas Bulwahn
` (3 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Lukas Bulwahn @ 2021-02-04 18:00 UTC (permalink / raw)
To: Christian Brauner, linux-fsdevel
Cc: Alexander Viro, Mauro Carvalho Chehab, linux-doc,
kernel-janitors, linux-kernel, Lukas Bulwahn
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 3/5] fs: update kernel-doc for may_create_in_sticky()
2021-02-04 18:00 [PATCH 0/5] kernel-doc fixes to latest fs changes Lukas Bulwahn
2021-02-04 18:00 ` [PATCH 1/5] fs: turn some comments into kernel-doc Lukas Bulwahn
2021-02-04 18:00 ` [PATCH 2/5] fs: update kernel-doc for vfs_rename() Lukas Bulwahn
@ 2021-02-04 18:00 ` Lukas Bulwahn
2021-02-04 18:00 ` [PATCH 4/5] fs: update kernel-doc for vfs_tmpfile() Lukas Bulwahn
` (2 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Lukas Bulwahn @ 2021-02-04 18:00 UTC (permalink / raw)
To: Christian Brauner, linux-fsdevel
Cc: Alexander Viro, Mauro Carvalho Chehab, linux-doc,
kernel-janitors, linux-kernel, Lukas Bulwahn
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 4/5] fs: update kernel-doc for vfs_tmpfile()
2021-02-04 18:00 [PATCH 0/5] kernel-doc fixes to latest fs changes Lukas Bulwahn
` (2 preceding siblings ...)
2021-02-04 18:00 ` [PATCH 3/5] fs: update kernel-doc for may_create_in_sticky() Lukas Bulwahn
@ 2021-02-04 18:00 ` Lukas Bulwahn
2021-02-04 18:00 ` [PATCH 5/5] fs: update kernel-doc for new mnt_userns argument Lukas Bulwahn
2021-03-01 12:51 ` [PATCH 0/5] kernel-doc fixes to latest fs changes Christian Brauner
5 siblings, 0 replies; 7+ messages in thread
From: Lukas Bulwahn @ 2021-02-04 18:00 UTC (permalink / raw)
To: Christian Brauner, linux-fsdevel
Cc: Alexander Viro, Mauro Carvalho Chehab, linux-doc,
kernel-janitors, linux-kernel, Lukas Bulwahn
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 5/5] fs: update kernel-doc for new mnt_userns argument
2021-02-04 18:00 [PATCH 0/5] kernel-doc fixes to latest fs changes Lukas Bulwahn
` (3 preceding siblings ...)
2021-02-04 18:00 ` [PATCH 4/5] fs: update kernel-doc for vfs_tmpfile() Lukas Bulwahn
@ 2021-02-04 18:00 ` Lukas Bulwahn
2021-03-01 12:51 ` [PATCH 0/5] kernel-doc fixes to latest fs changes Christian Brauner
5 siblings, 0 replies; 7+ messages in thread
From: Lukas Bulwahn @ 2021-02-04 18:00 UTC (permalink / raw)
To: Christian Brauner, linux-fsdevel
Cc: Alexander Viro, Mauro Carvalho Chehab, linux-doc,
kernel-janitors, linux-kernel, Lukas Bulwahn
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH 0/5] kernel-doc fixes to latest fs changes
2021-02-04 18:00 [PATCH 0/5] kernel-doc fixes to latest fs changes Lukas Bulwahn
` (4 preceding siblings ...)
2021-02-04 18:00 ` [PATCH 5/5] fs: update kernel-doc for new mnt_userns argument Lukas Bulwahn
@ 2021-03-01 12:51 ` Christian Brauner
5 siblings, 0 replies; 7+ messages in thread
From: Christian Brauner @ 2021-03-01 12:51 UTC (permalink / raw)
To: Lukas Bulwahn
Cc: linux-fsdevel, Alexander Viro, Mauro Carvalho Chehab, linux-doc,
kernel-janitors, linux-kernel
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
^ permalink raw reply [flat|nested] 7+ messages in thread