btrfs: update function comments
Subsystems (2)
David Sterba
maintainerPATCH 1/1 btrfs: update function comments
Update, reformat or reword function comments. This also removes the kdoc marker so we don't get reports when the function name is missing.
Changes made:
- remove kdoc markers
- reformat the brief description to be a proper sentence
- reword to imperative voice
- align parameter list
- fix typos
Signed-off-by David Sterba <[email protected]>
--- fs/btrfs/block-group.c | 20 +++---- fs/btrfs/ctree.c | 11 ++-- fs/btrfs/delalloc-space.c | 59 +++++++++---------- fs/btrfs/delayed-ref.c | 19 +++--- fs/btrfs/discard.c | 111 ++++++++++++++++++++---------------- fs/btrfs/extent_io.c | 59 ++++++++++--------- fs/btrfs/extent_map.c | 65 ++++++++++----------- fs/btrfs/file-item.c | 50 ++++++++-------- fs/btrfs/free-space-cache.c | 9 +-- fs/btrfs/inode.c | 14 ++--- fs/btrfs/ioctl.c | 2 +- fs/btrfs/ordered-data.c | 13 +++-- fs/btrfs/raid56.c | 4 +- fs/btrfs/reflink.c | 18 +++--- fs/btrfs/space-info.c | 16 +++--- fs/btrfs/tree-log.c | 2 +- fs/btrfs/ulist.c | 35 +++++++----- fs/btrfs/volumes.c | 43 +++++++------- fs/btrfs/zoned.c | 6 +- fs/btrfs/zstd.c | 2 +- 20 files changed, 289 insertions(+), 269 deletions(-)
fs/btrfs/block-group.c +10 -10
@@ -299,7 +299,7 @@ struct btrfs_block_group *btrfs_next_block_group(return cache; } -/** +/* * Check if we can do a NOCOW write for a given extent. * * @fs_info: The filesystem information object.
@@ -340,11 +340,9 @@ struct btrfs_block_group *btrfs_inc_nocow_writers(struct btrfs_fs_info *fs_info,return bg; } -/** +/* * Decrement the number of NOCOW writers in a block group. * -* @bg: The block group. -* * This is meant to be called after a previous call to btrfs_inc_nocow_writers(), * and on the block group returned by that call. Typically this is called after * creating an ordered extent for a NOCOW write, to prevent races with scrub and
@@ -1813,8 +1811,8 @@ static void set_avail_alloc_bits(struct btrfs_fs_info *fs_info, u64 flags)write_sequnlock (&fs_info->profiles_lock); } -/** -* Map a physical disk address to a list of logical addresses +/* +* Map a physical disk address to a list of logical addresses. * * @fs_info: the filesystem * @chunk_start: logical address of block group
@@ -3421,8 +3419,9 @@ int btrfs_update_block_group(struct btrfs_trans_handle *trans,return ret; } -/** -* btrfs_add_reserved_bytes - update the block_group and space info counters +/* +* Update the block_group and space info counters. +* * @cache: The cache we are manipulating * @ram_bytes: The number of bytes of file content, and will be same to * @num_bytes except for the compress path.
@@ -3465,8 +3464,9 @@ int btrfs_add_reserved_bytes(struct btrfs_block_group *cache,return ret; } -/** -* btrfs_free_reserved_bytes - update the block_group and space info counters +/* +* Update the block_group and space info counters. +* * @cache: The cache we are manipulating * @num_bytes: The number of bytes in question * @delalloc: The blocks are allocated for the delalloc write
fs/btrfs/ctree.c +6 -5
@@ -2347,7 +2347,7 @@ int btrfs_search_backwards(struct btrfs_root *root, struct btrfs_key *key,return ret; } -/** +/* * Search for a valid slot for the given path. * * @root: The root node of the tree.
@@ -3969,14 +3969,15 @@ void btrfs_extend_item(struct btrfs_path *path, u32 data_size) } } -/** -* setup_items_for_insert - Helper called before inserting one or more items -* to a leaf. Main purpose is to save stack depth by doing the bulk of the work -* in a function that doesn't call btrfs_search_slot +/* +* Make space in the node before inserting one or more items. * * @root: root we are inserting items to * @path: points to the leaf/slot where we are going to insert new items * @batch: information about the batch of items to insert +* +* Main purpose is to save stack depth by doing the bulk of the work in a +* function that doesn't call btrfs_search_slot */ static void setup_items_for_insert (struct btrfs_root *root,struct btrfs_path *path,const struct btrfs_item_batch *batch)
fs/btrfs/delalloc-space.c +30 -29
107 lines not on this page · raw message
fs/btrfs/delayed-ref.c +9 -10
@@ -71,14 +71,14 @@ int btrfs_should_throttle_delayed_refs(struct btrfs_trans_handle *trans)return btrfs_check_space_for_delayed_refs (trans->fs_info); } -/** -* Release a ref head's reservation +/* +* Release a ref head's reservation. * * @fs_info: the filesystem * @nr: number of items to drop * -* This drops the delayed ref head's count from the delayed refs rsv and frees -* any excess reservation we had. +* Drops the delayed ref head's count from the delayed refs rsv and free any +* excess reservation we had. */ void btrfs_delayed_refs_rsv_release (struct btrfs_fs_info *fs_info,int nr) {
@@ -104,8 +104,7 @@ void btrfs_delayed_refs_rsv_release(struct btrfs_fs_info *fs_info, int nr) }/* -* btrfs_update_delayed_refs_rsv - adjust the size of the delayed refs rsv -* @trans - the trans that may have generated delayed refs +* Adjust the size of the delayed refs rsv. * * This is to be called anytime we may have adjusted trans->delayed_ref_updates, * it'll calculate the additional size and add it to the delayed_refs_rsv.
@@ -139,8 +138,8 @@ void btrfs_update_delayed_refs_rsv(struct btrfs_trans_handle *trans) trans->delayed_ref_updates =0 ; } -/** -* Transfer bytes to our delayed refs rsv +/* +* Transfer bytes to our delayed refs rsv. * * @fs_info: the filesystem * @src: source block rsv to transfer from
@@ -188,8 +187,8 @@ void btrfs_migrate_to_delayed_refs_rsv(struct btrfs_fs_info *fs_info, delayed_refs_rsv->space_info, to_free); } -/** -* Refill based on our delayed refs usage +/* +* Refill based on our delayed refs usage. * * @fs_info: the filesystem * @flush: control how we can flush for this reservation.
fs/btrfs/discard.c +62 -49
228 lines not on this page · raw message
fs/btrfs/extent_io.c +31 -28
96 lines not on this page · raw message
fs/btrfs/extent_map.c +30 -35
140 lines not on this page · raw message
fs/btrfs/file-item.c +25 -25
102 lines not on this page · raw message
fs/btrfs/free-space-cache.c +3 -6
@@ -1369,8 +1369,8 @@ int btrfs_wait_cache_io(struct btrfs_trans_handle *trans, path, block_group->start); } -/** -* Write out cached info to an inode +/* +* Write out cached info to an inode. * * @root: root the inode belongs to * @inode: freespace inode we are writing out
@@ -3034,10 +3034,7 @@ void btrfs_remove_free_space_cache(struct btrfs_block_group *block_group) } -/** -* btrfs_is_free_space_trimmed - see if everything is trimmed -* @block_group: block_group of interest -* +/* * Walk @block_group's free space rb_tree to determine if everything is trimmed. */ bool btrfs_is_free_space_trimmed (struct btrfs_block_group *block_group)
fs/btrfs/inode.c +7 -7
@@ -6894,18 +6894,18 @@ static noinline int uncompress_inline(struct btrfs_path *path,return ret; } -/** -* btrfs_get_extent - Lookup the first extent overlapping a range in a file. +/* +* Lookup the first extent overlapping a range in a file. +* * @inode: file to search in * @page: page to read extent data into if the extent is inline * @pg_offset: offset into @page to copy to * @start: file offset * @len: length of range starting at @start * -* This returns the first &struct extent_map which overlaps with the given -* range, reading it from the B-tree and caching it if necessary. Note that -* there may be more extents which overlap the given range after the returned -* extent_map. +* Return the first &struct extent_map which overlaps the given range, reading +* it from the B-tree and caching it if necessary. Note that there may be more +* extents which overlap the given range after the returned extent_map. * * If @page is not NULL and the extent is inline, this also reads the extent * data directly into the page and marks the extent up to date in the io_tree.
@@ -11301,7 +11301,7 @@ void btrfs_update_inode_bytes(struct btrfs_inode *inode,spin_unlock (&inode->lock); } -/** +/* * Verify that there are no ordered extents for a given file range. * * @inode: The target inode.
fs/btrfs/ioctl.c +1 -1
@@ -4343,7 +4343,7 @@ void btrfs_update_ioctl_balance_args(struct btrfs_fs_info *fs_info,spin_unlock (&fs_info->balance_lock); } -/** +/* * Try to acquire fs_info::balance_mutex as well as set BTRFS_EXLCOP_BALANCE as * required. *
fs/btrfs/ordered-data.c +7 -6
@@ -144,7 +144,7 @@ static inline struct rb_node *tree_search(struct btrfs_ordered_inode_tree *tree,return ret; } -/** +/* * Add an ordered extent to the per-inode tree. * * @inode: Inode that this extent is for.
@@ -1020,17 +1020,18 @@ struct btrfs_ordered_extent *btrfs_lookup_first_ordered_range( }/* -* btrfs_flush_ordered_range - Lock the passed range and ensures all pending -* ordered extents in it are run to completion. +* Lock the passed range and ensures all pending ordered extents in it are run +* to completion. * * @inode: Inode whose ordered tree is to be searched * @start: Beginning of range to flush * @end: Last byte of range to lock * @cached_state: If passed, will return the extent state responsible for the -* locked range. It's the caller's responsibility to free the cached state. +* locked range. It's the caller's responsibility to free the +* cached state. * -* This function always returns with the given range locked, ensuring after it's -* called no order extent can be pending. +* Always return with the given range locked, ensuring after it's called no +* order extent can be pending. */ void btrfs_lock_and_flush_ordered_range(struct btrfs_inode *inode, u64 start, u64 end,
fs/btrfs/raid56.c +2 -2
@@ -908,8 +908,8 @@ static void raid_write_end_io(struct bio *bio)rbio_orig_end_io (rbio, err); } -/** -* Get a sector pointer specified by its @stripe_nr and @sector_nr +/* +* Get a sector pointer specified by its @stripe_nr and @sector_nr. * * @rbio: The raid bio * @stripe_nr: Stripe number, valid range [0, real_stripe)
fs/btrfs/reflink.c +9 -9
@@ -321,16 +321,16 @@ static int clone_copy_inline_extent(struct inode *dst, goto out; } -/** -* btrfs_clone() - clone a range from inode file to another +/* +* Clone a range from inode file to another. * -* @src: Inode to clone from -* @inode: Inode to clone to -* @off: Offset within source to start clone from -* @olen: Original length, passed by user, of range to clone -* @olen_aligned: Block-aligned value of olen -* @destoff: Offset within @inode to start clone -* @no_time_update: Whether to update mtime/ctime on the target inode +* @src: Inode to clone from +* @inode: Inode to clone to +* @off: Offset within source to start clone from +* @olen: Original length, passed by user, of range to clone +* @olen_aligned: Block-aligned value of olen +* @destoff: Offset within @inode to start clone +* @no_time_update: Whether to update mtime/ctime on the target inode */ static int btrfs_clone(struct inode *src, struct inode *inode, const u64 off, const u64 olen, const u64 olen_aligned,
fs/btrfs/space-info.c +8 -8
@@ -1493,8 +1493,8 @@ static void wait_reserve_ticket(struct btrfs_fs_info *fs_info,spin_unlock (&space_info->lock); } -/** -* Do the appropriate flushing and waiting for a ticket +/* +* Do the appropriate flushing and waiting for a ticket. * * @fs_info: the filesystem * @space_info: space info for the reservation
@@ -1596,8 +1596,8 @@ static inline bool can_ticket(enum btrfs_reserve_flush_enum flush) flush != BTRFS_RESERVE_FLUSH_EMERGENCY); } -/** -* Try to reserve bytes from the block_rsv's space +/* +* Try to reserve bytes from the block_rsv's space. * * @fs_info: the filesystem * @space_info: space info we want to allocate from
@@ -1736,8 +1736,8 @@ static int __reserve_bytes(struct btrfs_fs_info *fs_info, orig_bytes, flush); } -/** -* Trye to reserve metadata bytes from the block_rsv's space +/* +* Try to reserve metadata bytes from the block_rsv's space. * * @fs_info: the filesystem * @block_rsv: block_rsv we're allocating for
@@ -1771,8 +1771,8 @@ int btrfs_reserve_metadata_bytes(struct btrfs_fs_info *fs_info,return ret; } -/** -* Try to reserve data bytes for an allocation +/* +* Try to reserve data bytes for an allocation. * * @fs_info: the filesystem * @bytes: number of bytes we need
fs/btrfs/tree-log.c +1 -1
@@ -7330,7 +7330,7 @@ void btrfs_record_snapshot_destroy(struct btrfs_trans_handle *trans,mutex_unlock (&dir->log_mutex); } -/** +/* * Update the log after adding a new name for an inode. * * @trans: Transaction handle.
fs/btrfs/ulist.c +21 -14
@@ -38,8 +38,9 @@* loop would be similar to the above. */ -/** -* ulist_init - freshly initialize a ulist +/* +* Freshly initialize a ulist. +* * @ulist: the ulist to initialize * * Note: don't use this function to init an already used ulist, use
@@ -52,8 +53,9 @@ void ulist_init(struct ulist *ulist) ulist->nnodes =0 ; } -/** -* ulist_release - free up additionally allocated memory for the ulist +/* +* Free up additionally allocated memory for the ulist. +* * @ulist: the ulist from which to free the additional memory * * This is useful in cases where the base 'struct ulist' has been statically
@@ -71,8 +73,9 @@ void ulist_release(struct ulist *ulist)INIT_LIST_HEAD (&ulist->nodes); } -/** -* ulist_reinit - prepare a ulist for reuse +/* +* Prepare a ulist for reuse. +* * @ulist: ulist to be reused * * Free up all additional memory allocated for the list elements and reinit
@@ -84,8 +87,9 @@ void ulist_reinit(struct ulist *ulist)ulist_init (ulist); } -/** -* ulist_alloc - dynamically allocate a ulist +/* +* Dynamically allocate a ulist. +* * @gfp_mask: allocation flags to for base allocation * * The allocated ulist will be returned in an initialized state.
@@ -102,8 +106,9 @@ struct ulist *ulist_alloc(gfp_t gfp_mask)return ulist; } -/** -* ulist_free - free dynamically allocated ulist +/* +* Free dynamically allocated ulist. +* * @ulist: ulist to free * * It is not necessary to call ulist_release before.
@@ -164,8 +169,9 @@ static int ulist_rbtree_insert(struct ulist *ulist, struct ulist_node *ins)return 0 ; } -/** -* ulist_add - add an element to the ulist +/* +* Add an element to the ulist. +* * @ulist: ulist to add the element to * @val: value to add to ulist * @aux: auxiliary value to store along with val
@@ -243,8 +249,9 @@ int ulist_del(struct ulist *ulist, u64 val, u64 aux)return 0 ; } -/** -* ulist_next - iterate ulist +/* +* Iterate ulist. +* * @ulist: ulist to iterate * @uiter: iterator variable, initialized with ULIST_ITER_INIT(&iterator) *
fs/btrfs/volumes.c +23 -20
87 lines not on this page · raw message
fs/btrfs/zoned.c +3 -3
@@ -979,8 +979,8 @@ int btrfs_reset_sb_log_zones(struct block_device *bdev, int mirror) zone_sectors * BTRFS_NR_SB_LOG_ZONES, GFP_NOFS); } -/** -* btrfs_find_allocatable_zones - find allocatable zones within a given region +/* +* Find allocatable zones within a given region. * * @device: the device to allocate a region on * @hole_start: the position of the hole to allocate the region
@@ -1823,7 +1823,7 @@ struct btrfs_device *btrfs_zoned_get_device(struct btrfs_fs_info *fs_info,return device; } -/** +/* * Activate block group and underlying device zones * * @block_group: the block group to activate
fs/btrfs/zstd.c +1 -1
@@ -94,7 +94,7 @@ static inline struct workspace *list_to_workspace(struct list_head *list)void zstd_free_workspace (struct list_head *ws);struct list_head *zstd_alloc_workspace (unsigned int level); -/** +/* * Timer callback to free unused workspaces. * * @t: timer
Signature · 1 line
2.37.3