nilfs2-correct-return-value-kernel-doc-descriptions-for-ioctl-functions.patch removed from -mm tree
The quilt patch titled
Subject: nilfs2: correct return value kernel-doc descriptions for ioctl functions
has been removed from the -mm tree. Its filename was
nilfs2-correct-return-value-kernel-doc-descriptions-for-ioctl-functions.patch
This patch was dropped because it was merged into the mm-nonmm-stable branch of git://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm
------------------------------------------------------
From: Ryusuke Konishi <[email protected]>
Subject: nilfs2: correct return value kernel-doc descriptions for ioctl functions
Date: Fri, 10 Jan 2025 10:01:44 +0900
Patch series "nilfs2: fix kernel-doc comments for function return values", v2.
This series fixes the inadequacies in the return value descriptions in nilfs2's kernel-doc comments (mainly incorrect formatting), as well as the lack of return value descriptions themselves, and fixes most of the remaining warnings that are output when the kernel-doc script is run with the "-Wall" option.
This patch (of 7):
In the kernel-doc comments for functions, there are many cases where the format of the return value description is inaccurate, such as "Return
Value: ...", which causes many warnings to be output when the kernel-doc script is executed with the "-Wall" option.
This fixes such incorrectly formatted return value descriptions for ioctl functions.
---
fs/nilfs2/ioctl.c | 231 ++++++++++++++++++-------------------------- 1 file changed, 95 insertions(+), 136 deletions(-)
fs/nilfs2/ioctl.c renamed from fs/nilfs2/ioctl.c~nilfs2-correct-return-value-kernel-doc-descriptions-for-ioctl-functions +95 -136
@@ -33,17 +33,14 @@* @dofunc: concrete function of get/set metadata info * * Description: nilfs_ioctl_wrap_copy() gets/sets metadata info by means of -* calling dofunc() function on the basis of @argv argument. +* calling dofunc() function on the basis of @argv argument. If successful, +* the requested metadata information is copied to userspace memory. * -* Return Value: On success, 0 is returned and requested metadata info -* is copied into userspace. On error, one of the following -* negative error codes is returned. -* -* %-EINVAL - Invalid arguments from userspace. -* -* %-ENOMEM - Insufficient amount of memory available. -* -* %-EFAULT - Failure during execution of requested operation. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* * %-EFAULT - Failure during execution of requested operation. +* * %-EINVAL - Invalid arguments from userspace. +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_wrap_copy(struct the_nilfs *nilfs, struct nilfs_argv *argv, int dir,
@@ -190,13 +187,10 @@ static int nilfs_ioctl_getversion(struct* given checkpoint between checkpoint and snapshot state. This ioctl * is used in chcp and mkcp utilities. * -* Return Value: On success, 0 is returned and mode of a checkpoint is -* changed. On error, one of the following negative error codes -* is returned. -* -* %-EPERM - Operation not permitted. -* -* %-EFAULT - Failure during checkpoint mode changing. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* %-EFAULT - Failure during checkpoint mode changing. +* %-EPERM - Operation not permitted. */ static int nilfs_ioctl_change_cpmode (struct inode *inode,struct file *filp,unsigned int cmd,void __user *argp)
@@ -244,13 +238,10 @@ out:* checkpoint from NILFS2 file system. This ioctl is used in rmcp * utility. * -* Return Value: On success, 0 is returned and a checkpoint is -* removed. On error, one of the following negative error codes -* is returned. -* -* %-EPERM - Operation not permitted. -* -* %-EFAULT - Failure during checkpoint removing. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* %-EFAULT - Failure during checkpoint removing. +* %-EPERM - Operation not permitted. */ static int nilfs_ioctl_delete_checkpoint(struct inode *inode, struct file *filp,
@@ -296,7 +287,7 @@ out:* requested checkpoints. The NILFS_IOCTL_GET_CPINFO ioctl is used in * lscp utility and by nilfs_cleanerd daemon. * -* Return value: count of nilfs_cpinfo structures in output buffer. +* Return: Count of nilfs_cpinfo structures in output buffer. */ static ssize_t nilfs_ioctl_do_get_cpinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
@@ -320,17 +311,14 @@ nilfs_ioctl_do_get_cpinfo(struct the_nil* * Description: nilfs_ioctl_get_cpstat() returns information about checkpoints. * The NILFS_IOCTL_GET_CPSTAT ioctl is used by lscp, rmcp utilities -* and by nilfs_cleanerd daemon. +* and by nilfs_cleanerd daemon. The checkpoint statistics are copied to +* the userspace memory pointed to by @argp. * -* Return Value: On success, 0 is returned, and checkpoints information is -* copied into userspace pointer @argp. On error, one of the following -* negative error codes is returned. -* -* %-EIO - I/O error. -* -* %-ENOMEM - Insufficient amount of memory available. -* -* %-EFAULT - Failure during getting checkpoints statistics. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* * %-EFAULT - Failure during getting checkpoints statistics. +* * %-EIO - I/O error. +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_get_cpstat (struct inode *inode,struct file *filp,unsigned int cmd,void __user *argp)
@@ -363,7 +351,8 @@ static int nilfs_ioctl_get_cpstat(struct* info about requested segments. The NILFS_IOCTL_GET_SUINFO ioctl is used * in lssu, nilfs_resize utilities and by nilfs_cleanerd daemon. * -* Return value: count of nilfs_suinfo structures in output buffer. +* Return: Count of nilfs_suinfo structures in output buffer on success, +* or a negative error code on failure. */ static ssize_t nilfs_ioctl_do_get_suinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
@@ -387,17 +376,14 @@ nilfs_ioctl_do_get_suinfo(struct the_nil* * Description: nilfs_ioctl_get_sustat() returns segment usage statistics. * The NILFS_IOCTL_GET_SUSTAT ioctl is used in lssu, nilfs_resize utilities -* and by nilfs_cleanerd daemon. -* -* Return Value: On success, 0 is returned, and segment usage information is -* copied into userspace pointer @argp. On error, one of the following -* negative error codes is returned. -* -* %-EIO - I/O error. -* -* %-ENOMEM - Insufficient amount of memory available. +* and by nilfs_cleanerd daemon. The requested segment usage information is +* copied to the userspace memory pointed to by @argp. * -* %-EFAULT - Failure during getting segment usage statistics. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* * %-EFAULT - Failure during getting segment usage statistics. +* * %-EIO - I/O error. +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_get_sustat (struct inode *inode,struct file *filp,unsigned int cmd,void __user *argp)
@@ -430,7 +416,8 @@ static int nilfs_ioctl_get_sustat(struct* on virtual block addresses. The NILFS_IOCTL_GET_VINFO ioctl is used * by nilfs_cleanerd daemon. * -* Return value: count of nilfs_vinfo structures in output buffer. +* Return: Count of nilfs_vinfo structures in output buffer on success, or +* a negative error code on failure. */ static ssize_t nilfs_ioctl_do_get_vinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
@@ -457,7 +444,8 @@ nilfs_ioctl_do_get_vinfo(struct the_nilf* about descriptors of disk block numbers. The NILFS_IOCTL_GET_BDESCS ioctl * is used by nilfs_cleanerd daemon. * -* Return value: count of nilfs_bdescs structures in output buffer. +* Return: Count of nilfs_bdescs structures in output buffer on success, or +* a negative error code on failure. */ static ssize_t nilfs_ioctl_do_get_bdescs(struct the_nilfs *nilfs, __u64 *posp, int flags,
@@ -494,19 +482,15 @@ nilfs_ioctl_do_get_bdescs(struct the_nil* * Description: nilfs_ioctl_do_get_bdescs() function returns information * about descriptors of disk block numbers. The NILFS_IOCTL_GET_BDESCS ioctl -* is used by nilfs_cleanerd daemon. -* -* Return Value: On success, 0 is returned, and disk block descriptors are -* copied into userspace pointer @argp. On error, one of the following -* negative error codes is returned. -* -* %-EINVAL - Invalid arguments from userspace. +* is used by nilfs_cleanerd daemon. If successful, disk block descriptors +* are copied to userspace pointer @argp. * -* %-EIO - I/O error. -* -* %-ENOMEM - Insufficient amount of memory available. -* -* %-EFAULT - Failure during getting disk block descriptors. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* * %-EFAULT - Failure during getting disk block descriptors. +* * %-EINVAL - Invalid arguments from userspace. +* * %-EIO - I/O error. +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_get_bdescs (struct inode *inode,struct file *filp,unsigned int cmd,void __user *argp)
@@ -540,16 +524,12 @@ static int nilfs_ioctl_get_bdescs(struct* Description: nilfs_ioctl_move_inode_block() function registers data/node * buffer in the GC pagecache and submit read request. * -* Return Value: On success, 0 is returned. On error, one of the following -* negative error codes is returned. -* -* %-EIO - I/O error. -* -* %-ENOMEM - Insufficient amount of memory available. -* -* %-ENOENT - Requested block doesn't exist. -* -* %-EEXIST - Blocks conflict is detected. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* * %-EEXIST - Block conflict detected. +* * %-EIO - I/O error. +* * %-ENOENT - Requested block doesn't exist. +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_move_inode_block(struct inode *inode, struct nilfs_vdesc *vdesc,
@@ -604,8 +584,8 @@ static int nilfs_ioctl_move_inode_block(* blocks that garbage collector specified with the array of nilfs_vdesc * structures and stores them into page caches of GC inodes. * -* Return Value: Number of processed nilfs_vdesc structures or -* error code, otherwise. +* Return: Number of processed nilfs_vdesc structures on success, or +* a negative error code on failure. */ static int nilfs_ioctl_move_blocks (struct super_block *sb,struct nilfs_argv *argv,void *buf)
@@ -682,14 +662,11 @@ static int nilfs_ioctl_move_blocks(struc* in the period from p_start to p_end, excluding p_end itself. The checkpoints * which have been already deleted are ignored. * -* Return Value: Number of processed nilfs_period structures or -* error code, otherwise. -* -* %-EIO - I/O error. -* -* %-ENOMEM - Insufficient amount of memory available. -* -* %-EINVAL - invalid checkpoints. +* Return: Number of processed nilfs_period structures on success, or one of +* the following negative error codes on failure: +* * %-EINVAL - invalid checkpoints. +* * %-EIO - I/O error. +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_delete_checkpoints (struct the_nilfs *nilfs,struct nilfs_argv *argv,void *buf)
@@ -717,14 +694,11 @@ static int nilfs_ioctl_delete_checkpoint* Description: nilfs_ioctl_free_vblocknrs() function frees * the virtual block numbers specified by @buf and @argv->v_nmembs. * -* Return Value: Number of processed virtual block numbers or -* error code, otherwise. -* -* %-EIO - I/O error. -* -* %-ENOMEM - Insufficient amount of memory available. -* -* %-ENOENT - The virtual block number have not been allocated. +* Return: Number of processed virtual block numbers on success, or one of the +* following negative error codes on failure: +* * %-EIO - I/O error. +* * %-ENOENT - Unallocated virtual block number. +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_free_vblocknrs (struct the_nilfs *nilfs,struct nilfs_argv *argv,void *buf)
@@ -746,14 +720,11 @@ static int nilfs_ioctl_free_vblocknrs(st* Description: nilfs_ioctl_mark_blocks_dirty() function marks * metadata file or data blocks as dirty. * -* Return Value: Number of processed block descriptors or -* error code, otherwise. -* -* %-ENOMEM - Insufficient memory available. -* -* %-EIO - I/O error -* -* %-ENOENT - the specified block does not exist (hole block) +* Return: Number of processed block descriptors on success, or one of the +* following negative error codes on failure: +* * %-EIO - I/O error. +* * %-ENOENT - Non-existent block (hole block). +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_mark_blocks_dirty (struct the_nilfs *nilfs,struct nilfs_argv *argv,void *buf)
@@ -852,7 +823,7 @@ int nilfs_ioctl_prepare_clean_segments(s* from userspace. The NILFS_IOCTL_CLEAN_SEGMENTS ioctl is used by * nilfs_cleanerd daemon. * -* Return Value: On success, 0 is returned or error code, otherwise. +* Return: 0 on success, or a negative error code on failure. */ static int nilfs_ioctl_clean_segments (struct inode *inode,struct file *filp,unsigned int cmd,void __user *argp)
@@ -976,20 +947,14 @@ out:* and metadata are written out to the device when it successfully * returned. * -* Return Value: On success, 0 is retured. On errors, one of the following -* negative error code is returned. -* -* %-EROFS - Read only filesystem. -* -* %-EIO - I/O error -* -* %-ENOSPC - No space left on device (only in a panic state). -* -* %-ERESTARTSYS - Interrupted. -* -* %-ENOMEM - Insufficient memory available. -* -* %-EFAULT - Failure during execution of requested operation. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* * %-EFAULT - Failure during execution of requested operation. +* * %-EIO - I/O error. +* * %-ENOMEM - Insufficient memory available. +* * %-ENOSPC - No space left on device (only in a panic state). +* * %-ERESTARTSYS - Interrupted. +* * %-EROFS - Read only filesystem. */ static int nilfs_ioctl_sync (struct inode *inode,struct file *filp,unsigned int cmd,void __user *argp)
@@ -1023,7 +988,7 @@ static int nilfs_ioctl_sync(struct inode* @filp: file object * @argp: pointer on argument from userspace * -* Return Value: On success, 0 is returned or error code, otherwise. +* Return: 0 on success, or a negative error code on failure. */ static int nilfs_ioctl_resize (struct inode *inode,struct file *filp,void __user *argp)
@@ -1059,7 +1024,7 @@ out:* checks the arguments from userspace and calls nilfs_sufile_trim_fs, which * performs the actual trim operation. * -* Return Value: On success, 0 is returned or negative error code, otherwise. +* Return: 0 on success, or a negative error code on failure. */ static int nilfs_ioctl_trim_fs (struct inode *inode,void __user *argp) {
@@ -1101,7 +1066,7 @@ static int nilfs_ioctl_trim_fs(struct in* of segments in bytes and upper limit of segments in bytes. * The NILFS_IOCTL_SET_ALLOC_RANGE is used by nilfs_resize utility. * -* Return Value: On success, 0 is returned or error code, otherwise. +* Return: 0 on success, or a negative error code on failure. */ static int nilfs_ioctl_set_alloc_range (struct inode *inode,void __user *argp) {
@@ -1152,17 +1117,15 @@ out:* @dofunc: concrete function of getting metadata info * * Description: nilfs_ioctl_get_info() gets metadata info by means of -* calling dofunc() function. -* -* Return Value: On success, 0 is returned and requested metadata info -* is copied into userspace. On error, one of the following -* negative error codes is returned. -* -* %-EINVAL - Invalid arguments from userspace. +* calling dofunc() function. The requested metadata information is copied +* to userspace memory @argp. * -* %-ENOMEM - Insufficient amount of memory available. -* -* %-EFAULT - Failure during execution of requested operation. +* Return: 0 on success, or one of the following negative error codes on +* failure: +* * %-EFAULT - Failure during execution of requested operation. +* * %-EINVAL - Invalid arguments from userspace. +* * %-EIO - I/O error. +* * %-ENOMEM - Insufficient memory available. */ static int nilfs_ioctl_get_info(struct inode *inode, struct file *filp, unsigned int cmd, void __user *argp,
@@ -1202,18 +1165,14 @@ static int nilfs_ioctl_get_info(struct i* encapsulated in nilfs_argv and updates the segment usage info * according to the flags in nilfs_suinfo_update. * -* Return Value: On success, 0 is returned. On error, one of the -* following negative error codes is returned. -* -* %-EPERM - Not enough permissions -* -* %-EFAULT - Error copying input data -* -* %-EIO - I/O error. -* -* %-ENOMEM - Insufficient amount of memory available. -* -* %-EINVAL - Invalid values in input (segment number, flags or nblocks) +* Return: 0 on success, or one of the following negative error codes on +* failure: +* * %-EEXIST - Block conflict detected. +* * %-EFAULT - Error copying input data. +* * %-EINVAL - Invalid values in input (segment number, flags or nblocks). +* * %-EIO - I/O error. +* * %-ENOMEM - Insufficient memory available. +* * %-EPERM - Not enough permissions. */ static int nilfs_ioctl_set_suinfo (struct inode *inode,struct file *filp,unsigned int cmd,void __user *argp)
_
Patches currently in -mm which might be from [email protected] are