[PATCH 0/8] nilfs2: clean up kernel-doc warnings

[PATCH 0/8] nilfs2: clean up kernel-doc warnings

[Ryusuke Konishi]

Hi Andrew, please add this series to the queue for the next cycle.

This series fixes a number of formatting issues in kernel doc comments
that were detected as warnings by the kernel-doc script, making
violations more noticeable when adding or modifying kernel doc.

There are still warnings output by "kernel-doc -Wall", but they are
widespread, so I plan to fix them at another time while considering
priorities.

Thanks,
Ryusuke Konishi

Ryusuke Konishi (8):
  nilfs2: add missing argument description for __nilfs_error()
  nilfs2: add missing argument descriptions for ioctl-related helpers
  nilfs2: improve kernel-doc comments for b-tree node helpers
  nilfs2: fix incorrect kernel-doc declaration of nilfs_palloc_req
    structure
  nilfs2: add missing description of nilfs_btree_path structure
  nilfs2: describe the members of nilfs_bmap_operations structure
  nilfs2: fix inconsistencies in kernel-doc comments in segment.h
  nilfs2: fix missing initial short descriptions of kernel-doc comments

 fs/nilfs2/alloc.h   |  2 +-
 fs/nilfs2/bmap.c    |  2 +-
 fs/nilfs2/bmap.h    | 15 ++++++++++-
 fs/nilfs2/btnode.c  | 63 ++++++++++++++++++++++++++++++++++++++-------
 fs/nilfs2/btree.h   |  1 +
 fs/nilfs2/cpfile.c  | 32 +++++++++++------------
 fs/nilfs2/dat.c     | 17 +++++-------
 fs/nilfs2/ioctl.c   | 17 ++++++++++--
 fs/nilfs2/segment.h |  7 ++---
 fs/nilfs2/sufile.c  | 20 ++++++--------
 fs/nilfs2/super.c   |  4 +++
 11 files changed, 125 insertions(+), 55 deletions(-)

-- 
2.34.1

[PATCH 1/8] nilfs2: add missing argument description for __nilfs_error()

[Ryusuke Konishi]

Add missing argument description to __nilfs_error function and remove
the following warnings from kernel-doc script output:

 fs/nilfs2/super.c:121: warning: Function parameter or struct member 'sb'
  not described in '__nilfs_error'
 fs/nilfs2/super.c:121: warning: Function parameter or struct member
  'function' not described in '__nilfs_error'
 fs/nilfs2/super.c:121: warning: Function parameter or struct member 'fmt'
  not described in '__nilfs_error'

Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
---
 fs/nilfs2/super.c | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/fs/nilfs2/super.c b/fs/nilfs2/super.c
index 76e35e6773d1..8eb8dbc9f51c 100644
--- a/fs/nilfs2/super.c
+++ b/fs/nilfs2/super.c
@@ -105,6 +105,10 @@ static void nilfs_set_error(struct super_block *sb)
 
 /**
  * __nilfs_error() - report failure condition on a filesystem
+ * @sb:       super block instance
+ * @function: name of calling function
+ * @fmt:      format string for message to be output
+ * @...:      optional arguments to @fmt
  *
  * __nilfs_error() sets an ERROR_FS flag on the superblock as well as
  * reporting an error message.  This function should be called when
-- 
2.34.1

[PATCH 2/8] nilfs2: add missing argument descriptions for ioctl-related helpers

[Ryusuke Konishi]

Add missing argument descriptions and return value information to the
kernel-doc comments for ioctl helper functions, and eliminate the
following warnings output by the kernel-doc script:

 fs/nilfs2/ioctl.c:120: warning: Function parameter or struct member
  'dentry' not described in 'nilfs_fileattr_get'
 fs/nilfs2/ioctl.c:120: warning: Function parameter or struct member 'fa'
  not described in 'nilfs_fileattr_get'
 fs/nilfs2/ioctl.c:133: warning: Function parameter or struct member 'idmap'
  not described in 'nilfs_fileattr_set'
 fs/nilfs2/ioctl.c:133: warning: Function parameter or struct member
  'dentry' not described in 'nilfs_fileattr_set'
 fs/nilfs2/ioctl.c:133: warning: Function parameter or struct member 'fa'
  not described in 'nilfs_fileattr_set'
 fs/nilfs2/ioctl.c:164: warning: Function parameter or struct member 'inode'
  not described in 'nilfs_ioctl_getversion'
 fs/nilfs2/ioctl.c:164: warning: Function parameter or struct member 'argp'
  not described in 'nilfs_ioctl_getversion'

Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
---
 fs/nilfs2/ioctl.c | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/fs/nilfs2/ioctl.c b/fs/nilfs2/ioctl.c
index 297989e51ee6..fa77f78df681 100644
--- a/fs/nilfs2/ioctl.c
+++ b/fs/nilfs2/ioctl.c
@@ -115,7 +115,11 @@ static int nilfs_ioctl_wrap_copy(struct the_nilfs *nilfs,
 }
 
 /**
- * nilfs_fileattr_get - ioctl to support lsattr
+ * nilfs_fileattr_get - retrieve miscellaneous file attributes
+ * @dentry: the object to retrieve from
+ * @fa:     fileattr pointer
+ *
+ * Return: always 0 as success.
  */
 int nilfs_fileattr_get(struct dentry *dentry, struct fileattr *fa)
 {
@@ -127,7 +131,12 @@ int nilfs_fileattr_get(struct dentry *dentry, struct fileattr *fa)
 }
 
 /**
- * nilfs_fileattr_set - ioctl to support chattr
+ * nilfs_fileattr_set - change miscellaneous file attributes
+ * @idmap:  idmap of the mount
+ * @dentry: the object to change
+ * @fa:     fileattr pointer
+ *
+ * Return: 0 on success, or a negative error code on failure.
  */
 int nilfs_fileattr_set(struct mnt_idmap *idmap,
 		       struct dentry *dentry, struct fileattr *fa)
@@ -160,6 +169,10 @@ int nilfs_fileattr_set(struct mnt_idmap *idmap,
 
 /**
  * nilfs_ioctl_getversion - get info about a file's version (generation number)
+ * @inode: inode object
+ * @argp:  userspace memory where the generation number of @inode is stored
+ *
+ * Return: 0 on success, or %-EFAULT on error.
  */
 static int nilfs_ioctl_getversion(struct inode *inode, void __user *argp)
 {
-- 
2.34.1

[PATCH 3/8] nilfs2: improve kernel-doc comments for b-tree node helpers

[Ryusuke Konishi]

Revise kernel-doc comments for helper functions related to changing the
search key for b-tree node blocks, and eliminate the following warnings
output by the kernel-doc script:

 fs/nilfs2/btnode.c:175: warning: Function parameter or struct member 'btnc'
  not described in 'nilfs_btnode_prepare_change_key'
 fs/nilfs2/btnode.c:175: warning: Function parameter or struct member 'ctxt'
  not described in 'nilfs_btnode_prepare_change_key'
 fs/nilfs2/btnode.c:238: warning: Function parameter or struct member 'btnc'
  not described in 'nilfs_btnode_commit_change_key'
 fs/nilfs2/btnode.c:238: warning: Function parameter or struct member 'ctxt'
  not described in 'nilfs_btnode_commit_change_key'
 fs/nilfs2/btnode.c:278: warning: Function parameter or struct member 'btnc'
  not described in 'nilfs_btnode_abort_change_key'
 fs/nilfs2/btnode.c:278: warning: Function parameter or struct member 'ctxt'
  not described in 'nilfs_btnode_abort_change_key'

Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
---
 fs/nilfs2/btnode.c | 63 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 54 insertions(+), 9 deletions(-)

diff --git a/fs/nilfs2/btnode.c b/fs/nilfs2/btnode.c
index c034080c334b..57b4af5ad646 100644
--- a/fs/nilfs2/btnode.c
+++ b/fs/nilfs2/btnode.c
@@ -179,11 +179,32 @@ void nilfs_btnode_delete(struct buffer_head *bh)
 }
 
 /**
- * nilfs_btnode_prepare_change_key
- *  prepare to move contents of the block for old key to one of new key.
- *  the old buffer will not be removed, but might be reused for new buffer.
- *  it might return -ENOMEM because of memory allocation errors,
- *  and might return -EIO because of disk read errors.
+ * nilfs_btnode_prepare_change_key - prepare to change the search key of a
+ *                                   b-tree node block
+ * @btnc: page cache in which the b-tree node block is buffered
+ * @ctxt: structure for exchanging context information for key change
+ *
+ * nilfs_btnode_prepare_change_key() prepares to move the contents of the
+ * b-tree node block of the old key given in the "oldkey" member of @ctxt to
+ * the position of the new key given in the "newkey" member of @ctxt in the
+ * page cache @btnc.  Here, the key of the block is an index in units of
+ * blocks, and if the page and block sizes match, it matches the page index
+ * in the page cache.
+ *
+ * If the page size and block size match, this function attempts to move the
+ * entire folio, and in preparation for this, inserts the original folio into
+ * the new index of the cache.  If this insertion fails or if the page size
+ * and block size are different, it falls back to a copy preparation using
+ * nilfs_btnode_create_block(), inserts a new block at the position
+ * corresponding to "newkey", and stores the buffer head pointer in the
+ * "newbh" member of @ctxt.
+ *
+ * Note that the current implementation does not support folio sizes larger
+ * than the page size.
+ *
+ * Return: 0 on success, or the following negative error code on failure.
+ * * %-EIO	- I/O error (metadata corruption).
+ * * %-ENOMEM	- Insufficient memory available.
  */
 int nilfs_btnode_prepare_change_key(struct address_space *btnc,
 				    struct nilfs_btnode_chkey_ctxt *ctxt)
@@ -245,8 +266,21 @@ int nilfs_btnode_prepare_change_key(struct address_space *btnc,
 }
 
 /**
- * nilfs_btnode_commit_change_key
- *  commit the change_key operation prepared by prepare_change_key().
+ * nilfs_btnode_commit_change_key - commit the change of the search key of
+ *                                  a b-tree node block
+ * @btnc: page cache in which the b-tree node block is buffered
+ * @ctxt: structure for exchanging context information for key change
+ *
+ * nilfs_btnode_commit_change_key() executes the key change based on the
+ * context @ctxt prepared by nilfs_btnode_prepare_change_key().  If no valid
+ * block buffer is prepared in "newbh" of @ctxt (i.e., a full folio move),
+ * this function removes the folio from the old index and completes the move.
+ * Otherwise, it copies the block data and inherited flag states of "oldbh"
+ * to "newbh" and clears the "oldbh" from the cache.  In either case, the
+ * relocated buffer is marked as dirty.
+ *
+ * As with nilfs_btnode_prepare_change_key(), the current implementation does
+ * not support folio sizes larger than the page size.
  */
 void nilfs_btnode_commit_change_key(struct address_space *btnc,
 				    struct nilfs_btnode_chkey_ctxt *ctxt)
@@ -285,8 +319,19 @@ void nilfs_btnode_commit_change_key(struct address_space *btnc,
 }
 
 /**
- * nilfs_btnode_abort_change_key
- *  abort the change_key operation prepared by prepare_change_key().
+ * nilfs_btnode_abort_change_key - abort the change of the search key of a
+ *                                 b-tree node block
+ * @btnc: page cache in which the b-tree node block is buffered
+ * @ctxt: structure for exchanging context information for key change
+ *
+ * nilfs_btnode_abort_change_key() cancels the key change associated with the
+ * context @ctxt prepared via nilfs_btnode_prepare_change_key() and performs
+ * any necessary cleanup.  If no valid block buffer is prepared in "newbh" of
+ * @ctxt, this function removes the folio from the destination index and aborts
+ * the move.  Otherwise, it clears "newbh" from the cache.
+ *
+ * As with nilfs_btnode_prepare_change_key(), the current implementation does
+ * not support folio sizes larger than the page size.
  */
 void nilfs_btnode_abort_change_key(struct address_space *btnc,
 				   struct nilfs_btnode_chkey_ctxt *ctxt)
-- 
2.34.1

[PATCH 4/8] nilfs2: fix incorrect kernel-doc declaration of nilfs_palloc_req structure

[Ryusuke Konishi]

The "struct" keyword is missing from the kernel-doc comment of the
nilfs_palloc_req structure, so add it to eliminate the following warning
output by the kernel-doc script:

 fs/nilfs2/alloc.h:46: warning: cannot understand function prototype:
  'struct nilfs_palloc_req '

Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
---
 fs/nilfs2/alloc.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/fs/nilfs2/alloc.h b/fs/nilfs2/alloc.h
index d825a9faca6d..e19d7eb10084 100644
--- a/fs/nilfs2/alloc.h
+++ b/fs/nilfs2/alloc.h
@@ -37,7 +37,7 @@ void *nilfs_palloc_block_get_entry(const struct inode *, __u64,
 int nilfs_palloc_count_max_entries(struct inode *, u64, u64 *);
 
 /**
- * nilfs_palloc_req - persistent allocator request and reply
+ * struct nilfs_palloc_req - persistent allocator request and reply
  * @pr_entry_nr: entry number (vblocknr or inode number)
  * @pr_desc_bh: buffer head of the buffer containing block group descriptors
  * @pr_bitmap_bh: buffer head of the buffer containing a block group bitmap
-- 
2.34.1

[PATCH 5/8] nilfs2: add missing description of nilfs_btree_path structure

[Ryusuke Konishi]

Add missing kernel-doc comment for the 'bp_ctxt' member variable of
the nilfs_btree_path structure, and eliminate the following warning
output by the kenrel-doc script:

 fs/nilfs2/btree.h:39: warning: Function parameter or struct member
  'bp_ctxt' not described in 'nilfs_btree_path'

Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
---
 fs/nilfs2/btree.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/fs/nilfs2/btree.h b/fs/nilfs2/btree.h
index 92868e1a48ca..2a220f716c91 100644
--- a/fs/nilfs2/btree.h
+++ b/fs/nilfs2/btree.h
@@ -24,6 +24,7 @@
  * @bp_index: index of child node
  * @bp_oldreq: ptr end request for old ptr
  * @bp_newreq: ptr alloc request for new ptr
+ * @bp_ctxt: context information for changing the key of a b-tree node block
  * @bp_op: rebalance operation
  */
 struct nilfs_btree_path {
-- 
2.34.1

[PATCH 6/8] nilfs2: describe the members of nilfs_bmap_operations structure

[Ryusuke Konishi]

Add missing member variable descriptions in the kernel-doc comments
for the nilfs_bmap_operations structure, hiding the internal
operations with the "private:" tag.  This eliminates the following
warnings output by the kernel-doc script:

 fs/nilfs2/bmap.h:74: warning: Function parameter or struct member
  'bop_lookup' not described in 'nilfs_bmap_operations'
 fs/nilfs2/bmap.h:74: warning: Function parameter or struct member
  'bop_lookup_contig' not described in 'nilfs_bmap_operations'
 ...
 fs/nilfs2/bmap.h:74: warning: Function parameter or struct member
  'bop_gather_data' not described in 'nilfs_bmap_operations'

Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
---
 fs/nilfs2/bmap.h | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/fs/nilfs2/bmap.h b/fs/nilfs2/bmap.h
index 608168a5cb88..5f8c8c552620 100644
--- a/fs/nilfs2/bmap.h
+++ b/fs/nilfs2/bmap.h
@@ -44,6 +44,19 @@ struct nilfs_bmap_stats {
 
 /**
  * struct nilfs_bmap_operations - bmap operation table
+ * @bop_lookup:               single block search operation
+ * @bop_lookup_contig:        consecutive block search operation
+ * @bop_insert:               block insertion operation
+ * @bop_delete:               block delete operation
+ * @bop_clear:                block mapping resource release operation
+ * @bop_propagate:            operation to propagate dirty state towards the
+ *                            mapping root
+ * @bop_lookup_dirty_buffers: operation to collect dirty block buffers
+ * @bop_assign:               disk block address assignment operation
+ * @bop_mark:                 operation to mark in-use blocks as dirty for
+ *                            relocation by GC
+ * @bop_seek_key:             find valid block key operation
+ * @bop_last_key:             find last valid block key operation
  */
 struct nilfs_bmap_operations {
 	int (*bop_lookup)(const struct nilfs_bmap *, __u64, int, __u64 *);
@@ -66,7 +79,7 @@ struct nilfs_bmap_operations {
 	int (*bop_seek_key)(const struct nilfs_bmap *, __u64, __u64 *);
 	int (*bop_last_key)(const struct nilfs_bmap *, __u64 *);
 
-	/* The following functions are internal use only. */
+	/* private: internal use only */
 	int (*bop_check_insert)(const struct nilfs_bmap *, __u64);
 	int (*bop_check_delete)(struct nilfs_bmap *, __u64);
 	int (*bop_gather_data)(struct nilfs_bmap *, __u64 *, __u64 *, int);
-- 
2.34.1

[PATCH 7/8] nilfs2: fix inconsistencies in kernel-doc comments in segment.h

[Ryusuke Konishi]

Fix incorrect or missing variable names in the member variable
descriptions in the nilfs_recovery_info and nilfs_sc_info structures,
thereby eliminating the following warnings output by the kernel-doc
script:

 fs/nilfs2/segment.h:49: warning: Function parameter or struct member
  'ri_cno' not described in 'nilfs_recovery_info'
 fs/nilfs2/segment.h:49: warning: Function parameter or struct member
  'ri_lsegs_start_seq' not described in 'nilfs_recovery_info'
 fs/nilfs2/segment.h:49: warning: Excess struct member 'ri_ri_cno'
  description in 'nilfs_recovery_info'
 fs/nilfs2/segment.h:49: warning: Excess struct member 'ri_lseg_start_seq'
  description in 'nilfs_recovery_info'
 fs/nilfs2/segment.h:177: warning: Function parameter or struct member
  'sc_seq_accepted' not described in 'nilfs_sc_info'
 fs/nilfs2/segment.h:177: warning: Function parameter or struct member
  'sc_timer_task' not described in 'nilfs_sc_info'
 fs/nilfs2/segment.h:177: warning: Excess struct member 'sc_seq_accept'
  description in 'nilfs_sc_info'

Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
---
 fs/nilfs2/segment.h | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/fs/nilfs2/segment.h b/fs/nilfs2/segment.h
index 1060f72ebf5a..2499721ebcc9 100644
--- a/fs/nilfs2/segment.h
+++ b/fs/nilfs2/segment.h
@@ -22,10 +22,10 @@ struct nilfs_root;
  * struct nilfs_recovery_info - Recovery information
  * @ri_need_recovery: Recovery status
  * @ri_super_root: Block number of the last super root
- * @ri_ri_cno: Number of the last checkpoint
+ * @ri_cno: Number of the last checkpoint
  * @ri_lsegs_start: Region for roll-forwarding (start block number)
  * @ri_lsegs_end: Region for roll-forwarding (end block number)
- * @ri_lseg_start_seq: Sequence value of the segment at ri_lsegs_start
+ * @ri_lsegs_start_seq: Sequence value of the segment at ri_lsegs_start
  * @ri_used_segments: List of segments to be mark active
  * @ri_pseg_start: Block number of the last partial segment
  * @ri_seq: Sequence number on the last partial segment
@@ -107,7 +107,7 @@ struct nilfs_segsum_pointer {
  * @sc_wait_daemon: Daemon wait queue
  * @sc_wait_task: Start/end wait queue to control segctord task
  * @sc_seq_request: Request counter
- * @sc_seq_accept: Accepted request count
+ * @sc_seq_accepted: Accepted request count
  * @sc_seq_done: Completion counter
  * @sc_sync: Request of explicit sync operation
  * @sc_interval: Timeout value of background construction
@@ -115,6 +115,7 @@ struct nilfs_segsum_pointer {
  * @sc_lseg_stime: Start time of the latest logical segment
  * @sc_watermark: Watermark for the number of dirty buffers
  * @sc_timer: Timer for segctord
+ * @sc_timer_task: Thread woken up by @sc_timer
  * @sc_task: current thread of segctord
  */
 struct nilfs_sc_info {
-- 
2.34.1

[PATCH 8/8] nilfs2: fix missing initial short descriptions of kernel-doc comments

[Ryusuke Konishi]

Update some kernel-doc comments that are missing the initial short
description and fix the following warnings output by the kernel-doc
script:

 fs/nilfs2/bmap.c:353: warning: missing initial short description on line:
  * nilfs_bmap_lookup_dirty_buffers -
 fs/nilfs2/cpfile.c:708: warning: missing initial short description on line:
  * nilfs_cpfile_delete_checkpoint -
 fs/nilfs2/cpfile.c:972: warning: missing initial short description on line:
  * nilfs_cpfile_is_snapshot -
 fs/nilfs2/dat.c:275: warning: missing initial short description on line:
  * nilfs_dat_mark_dirty -
 fs/nilfs2/sufile.c:844: warning: missing initial short description on line:
  * nilfs_sufile_get_suinfo -

Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
---
 fs/nilfs2/bmap.c   |  2 +-
 fs/nilfs2/cpfile.c | 32 ++++++++++++++++----------------
 fs/nilfs2/dat.c    | 17 +++++++----------
 fs/nilfs2/sufile.c | 20 ++++++++------------
 4 files changed, 32 insertions(+), 39 deletions(-)

diff --git a/fs/nilfs2/bmap.c b/fs/nilfs2/bmap.c
index cd14ea25968c..c9e8d9a7d820 100644
--- a/fs/nilfs2/bmap.c
+++ b/fs/nilfs2/bmap.c
@@ -349,7 +349,7 @@ int nilfs_bmap_propagate(struct nilfs_bmap *bmap, struct buffer_head *bh)
 }
 
 /**
- * nilfs_bmap_lookup_dirty_buffers -
+ * nilfs_bmap_lookup_dirty_buffers - collect dirty block buffers
  * @bmap: bmap
  * @listp: pointer to buffer head list
  */
diff --git a/fs/nilfs2/cpfile.c b/fs/nilfs2/cpfile.c
index 69a5cced1e84..9c8d531cffa7 100644
--- a/fs/nilfs2/cpfile.c
+++ b/fs/nilfs2/cpfile.c
@@ -704,9 +704,15 @@ ssize_t nilfs_cpfile_get_cpinfo(struct inode *cpfile, __u64 *cnop, int mode,
 }
 
 /**
- * nilfs_cpfile_delete_checkpoint -
- * @cpfile:
- * @cno:
+ * nilfs_cpfile_delete_checkpoint - delete a checkpoint
+ * @cpfile: checkpoint file inode
+ * @cno:    checkpoint number to delete
+ *
+ * Return: 0 on success, or the following negative error code on failure.
+ * * %-EBUSY	- Checkpoint in use (snapshot specified).
+ * * %-EIO	- I/O error (including metadata corruption).
+ * * %-ENOENT	- No valid checkpoint found.
+ * * %-ENOMEM	- Insufficient memory available.
  */
 int nilfs_cpfile_delete_checkpoint(struct inode *cpfile, __u64 cno)
 {
@@ -968,21 +974,15 @@ static int nilfs_cpfile_clear_snapshot(struct inode *cpfile, __u64 cno)
 }
 
 /**
- * nilfs_cpfile_is_snapshot -
+ * nilfs_cpfile_is_snapshot - determine if checkpoint is a snapshot
  * @cpfile: inode of checkpoint file
- * @cno: checkpoint number
- *
- * Description:
- *
- * Return Value: On success, 1 is returned if the checkpoint specified by
- * @cno is a snapshot, or 0 if not. On error, one of the following negative
- * error codes is returned.
- *
- * %-EIO - I/O error.
- *
- * %-ENOMEM - Insufficient amount of memory available.
+ * @cno:    checkpoint number
  *
- * %-ENOENT - No such checkpoint.
+ * Return: 1 if the checkpoint specified by @cno is a snapshot, 0 if not, or
+ * the following negative error code on failure.
+ * * %-EIO	- I/O error (including metadata corruption).
+ * * %-ENOENT	- No such checkpoint.
+ * * %-ENOMEM	- Insufficient memory available.
  */
 int nilfs_cpfile_is_snapshot(struct inode *cpfile, __u64 cno)
 {
diff --git a/fs/nilfs2/dat.c b/fs/nilfs2/dat.c
index fc1caf63a42a..0bef662176a4 100644
--- a/fs/nilfs2/dat.c
+++ b/fs/nilfs2/dat.c
@@ -271,18 +271,15 @@ void nilfs_dat_abort_update(struct inode *dat,
 }
 
 /**
- * nilfs_dat_mark_dirty -
- * @dat: DAT file inode
+ * nilfs_dat_mark_dirty - mark the DAT block buffer containing the specified
+ *                        virtual block address entry as dirty
+ * @dat:      DAT file inode
  * @vblocknr: virtual block number
  *
- * Description:
- *
- * 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.
+ * Return: 0 on success, or the following negative error code on failure.
+ * * %-EINVAL	- Invalid DAT entry (internal code).
+ * * %-EIO	- I/O error (including metadata corruption).
+ * * %-ENOMEM	- Insufficient memory available.
  */
 int nilfs_dat_mark_dirty(struct inode *dat, __u64 vblocknr)
 {
diff --git a/fs/nilfs2/sufile.c b/fs/nilfs2/sufile.c
index 6748218be7c5..7bfc0860acee 100644
--- a/fs/nilfs2/sufile.c
+++ b/fs/nilfs2/sufile.c
@@ -840,21 +840,17 @@ int nilfs_sufile_resize(struct inode *sufile, __u64 newnsegs)
 }
 
 /**
- * nilfs_sufile_get_suinfo -
+ * nilfs_sufile_get_suinfo - get segment usage information
  * @sufile: inode of segment usage file
  * @segnum: segment number to start looking
- * @buf: array of suinfo
- * @sisz: byte size of suinfo
- * @nsi: size of suinfo array
+ * @buf:    array of suinfo
+ * @sisz:   byte size of suinfo
+ * @nsi:    size of suinfo array
  *
- * Description:
- *
- * Return Value: On success, 0 is returned and .... On error, one of the
- * following negative error codes is returned.
- *
- * %-EIO - I/O error.
- *
- * %-ENOMEM - Insufficient amount of memory available.
+ * Return: Count of segment usage info items stored in the output buffer on
+ * success, or the following negative error code on failure.
+ * * %-EIO	- I/O error (including metadata corruption).
+ * * %-ENOMEM	- Insufficient memory available.
  */
 ssize_t nilfs_sufile_get_suinfo(struct inode *sufile, __u64 segnum, void *buf,
 				unsigned int sisz, size_t nsi)
-- 
2.34.1