Re: [PATCH] PM: hibernate: Fix kernel-doc comment for add_rtree_block()

[Rafael J. Wysocki]

On Sun, Jun 7, 2026 at 1:06 PM Adi Nata
<adinata.softwareengineer@xxxxxxxxx> wrote:
>
> The kernel-doc comment for add_rtree_block() was missing @param
> descriptions for all four of its parameters (zone, gfp_mask,
> safe_needed, ca), causing build-time warnings (make W=1)
>
> kernel/power/snapshot.c:469: warning: Function parameter or
>   member 'zone' not described in 'add_rtree_block'
> kernel/power/snapshot.c:469: warning: Function parameter or
>   member 'gfp_mask' not described in 'add_rtree_block'
> kernel/power/snapshot.c:469: warning: Function parameter or
>   member 'safe_needed' not described in 'add_rtree_block'
> kernel/power/snapshot.c:469: warning: Function parameter or
>   member 'ca' not described in 'add_rtree_block'
>
> Add the missing @param tags, reusing the wording from the
> neighbouring alloc_rtree_node() for the shared parameters.
>
> Signed-off-by: Adi Nata <adinata.softwareengineer@xxxxxxxxx>

It's a static function that doesn't require a kerneldoc comment.

If you just want the warning to go away, replace the kerneldoc comment
marker /** with a regular comment marker /* in that comment.

Thanks!

> ---
>  kernel/power/snapshot.c | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/kernel/power/snapshot.c b/kernel/power/snapshot.c
> index a564650734dc..cd582be86412 100644
> --- a/kernel/power/snapshot.c
> +++ b/kernel/power/snapshot.c
> @@ -459,9 +459,13 @@ static struct rtree_node *alloc_rtree_node(gfp_t gfp_mask, int safe_needed,
>  }
>
>  /**
> - * add_rtree_block - Add a new leave node to the radix tree.
> + * add_rtree_block - Add a new leaf node to the radix tree of a memory zone.
> + * @zone: The memory zone's radix tree bitmap to extend with a new leaf block.
> + * @gfp_mask: GFP mask for the allocation.
> + * @safe_needed: Get pages not used before hibernation (restore only)
> + * @ca: Pointer to a linked list of pages ("a chain") to allocate from
>   *
> - * The leave nodes need to be allocated in order to keep the leaves
> + * The leaf nodes need to be allocated in order to keep the leaves
>   * linked list in order. This is guaranteed by the zone->blocks
>   * counter.
>   */
> --
> 2.47.3
>
>