[PATCH -next] btrfs: Fix kernel-doc formatting issues

[PATCH -next] btrfs: Fix kernel-doc formatting issues

[Yang Li]

Add function names to the kernel-doc of some functions and upgrade
descriptions of some parameters in it.

The warnings were found by running scripts/kernel-doc, which is
caused by using 'make W=1'.

Reported-by: Abaci Robot <abaci@linux.alibaba.com>
Signed-off-by: Yang Li <yang.lee@linux.alibaba.com>
---
 fs/btrfs/delalloc-space.c |  6 +++---
 fs/btrfs/extent_io.c      | 15 ++++++++-------
 fs/btrfs/space-info.c     | 10 +++++-----
 fs/btrfs/zoned.c          |  2 +-
 4 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/fs/btrfs/delalloc-space.c b/fs/btrfs/delalloc-space.c
index fb46a28f5065..1ca5f96fce66 100644
--- a/fs/btrfs/delalloc-space.c
+++ b/fs/btrfs/delalloc-space.c
@@ -194,7 +194,7 @@ void btrfs_free_reserved_data_space(struct btrfs_inode *inode,
 }
 
 /**
- * Release any excessive reservation
+ * btrfs_inode_rsv_release() - Release any excessive reservation
  *
  * @inode:       the inode we need to release from
  * @qgroup_free: free or convert qgroup meta. Unlike normal operation, qgroup
@@ -366,7 +366,7 @@ int btrfs_delalloc_reserve_metadata(struct btrfs_inode *inode, u64 num_bytes)
 }
 
 /**
- * Release a metadata reservation for an inode
+ * btrfs_delalloc_release_metadata() - Release a metadata reservation for an inode
  *
  * @inode: the inode to release the reservation for.
  * @num_bytes: the number of bytes we are releasing.
@@ -464,7 +464,7 @@ int btrfs_delalloc_reserve_space(struct btrfs_inode *inode,
 }
 
 /**
- * Release data and metadata space for delalloc
+ * btrfs_delalloc_release_space() - Release data and metadata space for delalloc
  *
  * @inode:       inode we're releasing space for
  * @reserved:    list of changed/reserved ranges
diff --git a/fs/btrfs/extent_io.c b/fs/btrfs/extent_io.c
index 9234d96a7fd5..1b38c7e6c900 100644
--- a/fs/btrfs/extent_io.c
+++ b/fs/btrfs/extent_io.c
@@ -399,7 +399,7 @@ static struct rb_node *tree_insert(struct rb_root *root,
 }
 
 /**
- * Search @tree for an entry that contains @offset. Such entry would have
+ * __etree_search() - Search @tree for an entry that contains @offset. Such entry would have
  * entry->start <= offset && entry->end >= offset.
  *
  * @tree:       the tree to search
@@ -1598,7 +1598,7 @@ int find_first_extent_bit(struct extent_io_tree *tree, u64 start,
 }
 
 /**
- * Find a contiguous area of bits
+ * find_contiguous_extent_bit() - Find a contiguous area of bits
  *
  * @tree:      io tree to check
  * @start:     offset to start the search from
@@ -1636,7 +1636,8 @@ int find_contiguous_extent_bit(struct extent_io_tree *tree, u64 start,
 }
 
 /**
- * Find the first range that has @bits not set. This range could start before
+ * find_first_clear_extent_bit() - Find the first range that has @bits not set.
+ *				   This range could start before.
  * @start.
  *
  * @tree:      the tree to search
@@ -3185,15 +3186,14 @@ struct bio *btrfs_bio_clone_partial(struct bio *orig, u64 offset, u64 size)
 }
 
 /**
- * Attempt to add a page to bio
+ * btrfs_bio_add_page() - Attempt to add a page to bio
  *
- * @bio:	destination bio
+ * @bio_ctrl:	record both the bio, and its bio_flags
  * @page:	page to add to the bio
  * @disk_bytenr:  offset of the new bio or to check whether we are adding
  *                a contiguous page to the previous one
  * @pg_offset:	starting offset in the page
  * @size:	portion of page that we want to write
- * @prev_bio_flags:  flags of previous bio to see if we can merge the current one
  * @bio_flags:	flags of the current bio to see if we can merge them
  *
  * Attempt to add a page to bio considering stripe alignment etc.
@@ -4933,7 +4933,8 @@ int btree_write_cache_pages(struct address_space *mapping,
 }
 
 /**
- * Walk the list of dirty pages of the given address space and write all of them.
+ * extent_write_cache_pages() - Walk the list of dirty pages of the given
+ *				address space and write all of them.
  *
  * @mapping: address space structure to write
  * @wbc:     subtract the number of written pages from *@wbc->nr_to_write
diff --git a/fs/btrfs/space-info.c b/fs/btrfs/space-info.c
index dbf8bfb8fcb3..86da4310a07a 100644
--- a/fs/btrfs/space-info.c
+++ b/fs/btrfs/space-info.c
@@ -1362,7 +1362,7 @@ static void wait_reserve_ticket(struct btrfs_fs_info *fs_info,
 }
 
 /**
- * Do the appropriate flushing and waiting for a ticket
+ * handle_reserve_ticket() - Do the appropriate flushing and waiting for a ticket
  *
  * @fs_info:    the filesystem
  * @space_info: space info for the reservation
@@ -1455,7 +1455,7 @@ static inline bool can_steal(enum btrfs_reserve_flush_enum flush)
 }
 
 /**
- * Try to reserve bytes from the block_rsv's space
+ * __reserve_bytes() - Try to reserve bytes from the block_rsv's space
  *
  * @fs_info:    the filesystem
  * @space_info: space info we want to allocate from
@@ -1581,9 +1581,9 @@ static int __reserve_bytes(struct btrfs_fs_info *fs_info,
 }
 
 /**
- * Trye to reserve metadata bytes from the block_rsv's space
+ * btrfs_reserve_metadata_bytes() - Trye to reserve metadata bytes from the block_rsv's space
  *
- * @root:       the root we're allocating for
+ * @fs_info:    the filesystem
  * @block_rsv:  block_rsv we're allocating for
  * @orig_bytes: number of bytes we want
  * @flush:      whether or not we can flush to make our reservation
@@ -1616,7 +1616,7 @@ int btrfs_reserve_metadata_bytes(struct btrfs_fs_info *fs_info,
 }
 
 /**
- * Try to reserve data bytes for an allocation
+ * btrfs_reserve_data_bytes() - Try to reserve data bytes for an allocation
  *
  * @fs_info: the filesystem
  * @bytes:   number of bytes we need
diff --git a/fs/btrfs/zoned.c b/fs/btrfs/zoned.c
index 6b3d7b65368b..cdc952bcfb9d 100644
--- a/fs/btrfs/zoned.c
+++ b/fs/btrfs/zoned.c
@@ -1781,7 +1781,7 @@ struct btrfs_device *btrfs_zoned_get_device(struct btrfs_fs_info *fs_info,
 }
 
 /**
- * Activate block group and underlying device zones
+ * btrfs_zone_activate() - Activate block group and underlying device zones
  *
  * @block_group: the block group to activate
  *
-- 
2.20.1.7.g153144c

Re: [PATCH -next] btrfs: Fix kernel-doc formatting issues

[Randy Dunlap]

On 12/15/21 23:08, Yang Li wrote:
> Add function names to the kernel-doc of some functions and upgrade
> descriptions of some parameters in it.
> 
> The warnings were found by running scripts/kernel-doc, which is
> caused by using 'make W=1'.
> 
> Reported-by: Abaci Robot <abaci@linux.alibaba.com>
> Signed-off-by: Yang Li <yang.lee@linux.alibaba.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

thanks.

> ---
>  fs/btrfs/delalloc-space.c |  6 +++---
>  fs/btrfs/extent_io.c      | 15 ++++++++-------
>  fs/btrfs/space-info.c     | 10 +++++-----
>  fs/btrfs/zoned.c          |  2 +-
>  4 files changed, 17 insertions(+), 16 deletions(-)
> 
> diff --git a/fs/btrfs/delalloc-space.c b/fs/btrfs/delalloc-space.c
> index fb46a28f5065..1ca5f96fce66 100644
> --- a/fs/btrfs/delalloc-space.c
> +++ b/fs/btrfs/delalloc-space.c
> @@ -194,7 +194,7 @@ void btrfs_free_reserved_data_space(struct btrfs_inode *inode,
>  }
>  
>  /**
> - * Release any excessive reservation
> + * btrfs_inode_rsv_release() - Release any excessive reservation
>   *
>   * @inode:       the inode we need to release from
>   * @qgroup_free: free or convert qgroup meta. Unlike normal operation, qgroup
> @@ -366,7 +366,7 @@ int btrfs_delalloc_reserve_metadata(struct btrfs_inode *inode, u64 num_bytes)
>  }
>  
>  /**
> - * Release a metadata reservation for an inode
> + * btrfs_delalloc_release_metadata() - Release a metadata reservation for an inode
>   *
>   * @inode: the inode to release the reservation for.
>   * @num_bytes: the number of bytes we are releasing.
> @@ -464,7 +464,7 @@ int btrfs_delalloc_reserve_space(struct btrfs_inode *inode,
>  }
>  
>  /**
> - * Release data and metadata space for delalloc
> + * btrfs_delalloc_release_space() - Release data and metadata space for delalloc
>   *
>   * @inode:       inode we're releasing space for
>   * @reserved:    list of changed/reserved ranges
> diff --git a/fs/btrfs/extent_io.c b/fs/btrfs/extent_io.c
> index 9234d96a7fd5..1b38c7e6c900 100644
> --- a/fs/btrfs/extent_io.c
> +++ b/fs/btrfs/extent_io.c
> @@ -399,7 +399,7 @@ static struct rb_node *tree_insert(struct rb_root *root,
>  }
>  
>  /**
> - * Search @tree for an entry that contains @offset. Such entry would have
> + * __etree_search() - Search @tree for an entry that contains @offset. Such entry would have
>   * entry->start <= offset && entry->end >= offset.
>   *
>   * @tree:       the tree to search
> @@ -1598,7 +1598,7 @@ int find_first_extent_bit(struct extent_io_tree *tree, u64 start,
>  }
>  
>  /**
> - * Find a contiguous area of bits
> + * find_contiguous_extent_bit() - Find a contiguous area of bits
>   *
>   * @tree:      io tree to check
>   * @start:     offset to start the search from
> @@ -1636,7 +1636,8 @@ int find_contiguous_extent_bit(struct extent_io_tree *tree, u64 start,
>  }
>  
>  /**
> - * Find the first range that has @bits not set. This range could start before
> + * find_first_clear_extent_bit() - Find the first range that has @bits not set.
> + *				   This range could start before.
>   * @start.
>   *
>   * @tree:      the tree to search
> @@ -3185,15 +3186,14 @@ struct bio *btrfs_bio_clone_partial(struct bio *orig, u64 offset, u64 size)
>  }
>  
>  /**
> - * Attempt to add a page to bio
> + * btrfs_bio_add_page() - Attempt to add a page to bio
>   *
> - * @bio:	destination bio
> + * @bio_ctrl:	record both the bio, and its bio_flags
>   * @page:	page to add to the bio
>   * @disk_bytenr:  offset of the new bio or to check whether we are adding
>   *                a contiguous page to the previous one
>   * @pg_offset:	starting offset in the page
>   * @size:	portion of page that we want to write
> - * @prev_bio_flags:  flags of previous bio to see if we can merge the current one
>   * @bio_flags:	flags of the current bio to see if we can merge them
>   *
>   * Attempt to add a page to bio considering stripe alignment etc.
> @@ -4933,7 +4933,8 @@ int btree_write_cache_pages(struct address_space *mapping,
>  }
>  
>  /**
> - * Walk the list of dirty pages of the given address space and write all of them.
> + * extent_write_cache_pages() - Walk the list of dirty pages of the given
> + *				address space and write all of them.
>   *
>   * @mapping: address space structure to write
>   * @wbc:     subtract the number of written pages from *@wbc->nr_to_write
> diff --git a/fs/btrfs/space-info.c b/fs/btrfs/space-info.c
> index dbf8bfb8fcb3..86da4310a07a 100644
> --- a/fs/btrfs/space-info.c
> +++ b/fs/btrfs/space-info.c
> @@ -1362,7 +1362,7 @@ static void wait_reserve_ticket(struct btrfs_fs_info *fs_info,
>  }
>  
>  /**
> - * Do the appropriate flushing and waiting for a ticket
> + * handle_reserve_ticket() - Do the appropriate flushing and waiting for a ticket
>   *
>   * @fs_info:    the filesystem
>   * @space_info: space info for the reservation
> @@ -1455,7 +1455,7 @@ static inline bool can_steal(enum btrfs_reserve_flush_enum flush)
>  }
>  
>  /**
> - * Try to reserve bytes from the block_rsv's space
> + * __reserve_bytes() - Try to reserve bytes from the block_rsv's space
>   *
>   * @fs_info:    the filesystem
>   * @space_info: space info we want to allocate from
> @@ -1581,9 +1581,9 @@ static int __reserve_bytes(struct btrfs_fs_info *fs_info,
>  }
>  
>  /**
> - * Trye to reserve metadata bytes from the block_rsv's space
> + * btrfs_reserve_metadata_bytes() - Trye to reserve metadata bytes from the block_rsv's space
>   *
> - * @root:       the root we're allocating for
> + * @fs_info:    the filesystem
>   * @block_rsv:  block_rsv we're allocating for
>   * @orig_bytes: number of bytes we want
>   * @flush:      whether or not we can flush to make our reservation
> @@ -1616,7 +1616,7 @@ int btrfs_reserve_metadata_bytes(struct btrfs_fs_info *fs_info,
>  }
>  
>  /**
> - * Try to reserve data bytes for an allocation
> + * btrfs_reserve_data_bytes() - Try to reserve data bytes for an allocation
>   *
>   * @fs_info: the filesystem
>   * @bytes:   number of bytes we need
> diff --git a/fs/btrfs/zoned.c b/fs/btrfs/zoned.c
> index 6b3d7b65368b..cdc952bcfb9d 100644
> --- a/fs/btrfs/zoned.c
> +++ b/fs/btrfs/zoned.c
> @@ -1781,7 +1781,7 @@ struct btrfs_device *btrfs_zoned_get_device(struct btrfs_fs_info *fs_info,
>  }
>  
>  /**
> - * Activate block group and underlying device zones
> + * btrfs_zone_activate() - Activate block group and underlying device zones
>   *
>   * @block_group: the block group to activate
>   *
> 

-- 
~Randy

Re: [PATCH -next] btrfs: Fix kernel-doc formatting issues

[David Sterba]

On Thu, Dec 16, 2021 at 03:08:13PM +0800, Yang Li wrote:
> Add function names to the kernel-doc of some functions and upgrade
> descriptions of some parameters in it.
> 
> The warnings were found by running scripts/kernel-doc, which is
> caused by using 'make W=1'.

Thanks, we care only about the argument list that the kdoc format and
script can verify, the rest is not really useful for internal functions
and makes it less pleasant to read.  The script will report that though
but we won't fix it, rather would like to see the script updated to
skip that.