kevin/linux
1
Fork 0
Code

nilfs2: improve kernel-doc comments for b-tree node helpers

Browse Source 
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'

Link: https://lkml.kernel.org/r/20240816074319.3253-4-konishi.ryusuke@gmail.com
Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
This commit is contained in:
Ryusuke Konishi 2024-08-16 16:43:14 +09:00 committed by Andrew Morton
parent 3e62c5d7d0
commit 60d8b01e55
1 changed files with 54 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
fs/nilfs2/btnode.c
View File

@ -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 @@ retry:
}
/**
* 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)