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

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

[Adi Nata]

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@gmail.com>
---
 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

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@gmail.com> 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@gmail.com>

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
>
>