Re: [PATCH -next] dm: vdo: Add missing kernel-doc function comments.

[Matthew Sakai <msakai@redhat.com>]

On 7/12/24 04:12, Yang Li wrote:
> Add missing kernel-doc function comments to enhance code readability and
> maintainability in accordance with the kernel coding standards.
> 
> Reported-by: Abaci Robot <abaci@linux.alibaba.com>
> Closes: https://bugzilla.openanolis.cn/show_bug.cgi?id=9518
> Signed-off-by: Yang Li <yang.lee@linux.alibaba.com>

I appreciate the patch, but some of these descriptions are not correct.
You can fix the patch if you'd like, or I can create a patch my self to 
add these kernel-doc comments.

Matt Sakai

> ---
>   drivers/md/dm-vdo/repair.c | 6 ++++++
>   1 file changed, 6 insertions(+)
> 
> diff --git a/drivers/md/dm-vdo/repair.c b/drivers/md/dm-vdo/repair.c
> index ff09e4a14333..8947e6092a91 100644
> --- a/drivers/md/dm-vdo/repair.c
> +++ b/drivers/md/dm-vdo/repair.c
> @@ -319,6 +319,7 @@ static bool __must_check abort_on_error(int result, struct repair_completion *re
>   /**
>    * drain_slab_depot() - Flush out all dirty refcounts blocks now that they have been rebuilt or
>    *                      recovered.
> + * @completion: The completion to convert.

This is the repair completion. There is nothing being converted here.

>    */
>   static void drain_slab_depot(struct vdo_completion *completion)
>   {
> @@ -656,6 +657,7 @@ static void rebuild_reference_counts(struct vdo_completion *completion)
>   
>   /**
>    * increment_recovery_point() - Move the given recovery point forward by one entry.
> + * @point: The location of the next recovery journal entry to apply.

This is the recovery point to increment. It is not the "next" entry, and 
this function doesn't care what the caller will use the recovery point for.

>    */
>   static void increment_recovery_point(struct recovery_point *point)
>   {
> @@ -953,6 +955,7 @@ static void abort_block_map_recovery(struct repair_completion *repair, int resul
>   /**
>    * find_entry_starting_next_page() - Find the first journal entry after a given entry which is not
>    *                                   on the same block map page.
> + * @repair: The repair completion.
>    * @current_entry: The entry to search from.
>    * @needs_sort: Whether sorting is needed to proceed.
>    *
> @@ -1219,6 +1222,7 @@ static bool __must_check is_exact_recovery_journal_block(const struct recovery_j
>   
>   /**
>    * find_recovery_journal_head_and_tail() - Find the tail and head of the journal.
> + * @repair: The repair completion.
>    *
>    * Return: True if there were valid journal blocks.
>    */
> @@ -1447,6 +1451,7 @@ static int validate_heads(struct repair_completion *repair)
>   
>   /**
>    * extract_new_mappings() - Find all valid new mappings to be applied to the block map.
> + * @repair: The repair completion.
>    *
>    * The mappings are extracted from the journal and stored in a sortable array so that all of the
>    * mappings to be applied to a given block map page can be done in a single page fetch.
> @@ -1501,6 +1506,7 @@ static int extract_new_mappings(struct repair_completion *repair)
>   /**
>    * compute_usages() - Compute the lbns in use and block map data blocks counts from the tail of
>    *                    the journal.
> + * @repair: The repair completion.
>    */
>   static noinline int compute_usages(struct repair_completion *repair)
>   {