Re: [PATCH] PM: hibernate: Mark undocumented snapshot helpers as non-kernel-doc

[Rafael J. Wysocki (Intel)]

On Wed, Jun 10, 2026 at 1:16 AM Adi Nata
<adinata.softwareengineer@xxxxxxxxx> wrote:
>
> Several helpers in snapshot.c are introduced with kernel-doc (/**)
> comment blocks but do not describe their parameters with @param
> tags.This emits warnings when building
> with extra warnings enabled (make W=1), for example:
> 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'
>
> These are file-local implementation details, not part of the
> exported kernel API documented under Documentation/. Replace the
> kernel-doc markers with plain block comments for the affected
> functions.
>
> Properly documented symbols such as
> alloc_rtree_node(), snapshot_read_next() and snapshot_write_next()
> remain unchanged.
>
> Signed-off-by: Adi Nata <adinata.softwareengineer@xxxxxxxxx>
> ---
>  kernel/power/snapshot.c | 42 ++++++++++++++++++++---------------------
>  1 file changed, 21 insertions(+), 21 deletions(-)
>
> diff --git a/kernel/power/snapshot.c b/kernel/power/snapshot.c
> index a564650734dc..552958f58359 100644
> --- a/kernel/power/snapshot.c
> +++ b/kernel/power/snapshot.c
> @@ -458,7 +458,7 @@ static struct rtree_node *alloc_rtree_node(gfp_t gfp_mask, int safe_needed,
>         return node;
>  }
>
> -/**
> +/*
>   * add_rtree_block - Add a new leave node to the radix tree.
>   *
>   * The leave nodes need to be allocated in order to keep the leaves
> @@ -528,7 +528,7 @@ static int add_rtree_block(struct mem_zone_bm_rtree *zone, gfp_t gfp_mask,
>  static void free_zone_bm_rtree(struct mem_zone_bm_rtree *zone,
>                                int clear_nosave_free);
>
> -/**
> +/*
>   * create_zone_bm_rtree - Create a radix tree for one zone.
>   *
>   * Allocated the mem_zone_bm_rtree structure and initializes it.
> @@ -566,7 +566,7 @@ static struct mem_zone_bm_rtree *create_zone_bm_rtree(gfp_t gfp_mask,
>         return zone;
>  }
>
> -/**
> +/*
>   * free_zone_bm_rtree - Free the memory of the radix tree.
>   *
>   * Free all node pages of the radix tree. The mem_zone_bm_rtree
> @@ -678,7 +678,7 @@ static int create_mem_extents(struct list_head *list, gfp_t gfp_mask)
>         return 0;
>  }
>
> -/**
> +/*
>   * memory_bm_create - Allocate memory for a memory bitmap.
>   */
>  static int memory_bm_create(struct memory_bitmap *bm, gfp_t gfp_mask,
> @@ -720,7 +720,7 @@ static int memory_bm_create(struct memory_bitmap *bm, gfp_t gfp_mask,
>         goto Exit;
>  }
>
> -/**
> +/*
>   * memory_bm_free - Free memory occupied by the memory bitmap.
>   * @bm: Memory bitmap.
>   */
> @@ -736,7 +736,7 @@ static void memory_bm_free(struct memory_bitmap *bm, int clear_nosave_free)
>         INIT_LIST_HEAD(&bm->zones);
>  }
>
> -/**
> +/*
>   * memory_bm_find_bit - Find the bit for a given PFN in a memory bitmap.
>   *
>   * Find the bit in memory bitmap @bm that corresponds to the given PFN.
> @@ -988,7 +988,7 @@ static void memory_bm_recycle(struct memory_bitmap *bm)
>         }
>  }
>
> -/**
> +/*
>   * register_nosave_region - Register a region of unsaveable memory.
>   *
>   * Register a range of page frames the contents of which should not be saved
> @@ -1305,7 +1305,7 @@ static unsigned int count_free_highmem_pages(void)
>         return cnt;
>  }
>
> -/**
> +/*
>   * saveable_highmem_page - Check if a highmem page is saveable.
>   *
>   * Determine whether a highmem page should be included in a hibernation image.
> @@ -1362,7 +1362,7 @@ static unsigned int count_highmem_pages(void)
>  }
>  #endif /* CONFIG_HIGHMEM */
>
> -/**
> +/*
>   * saveable_page - Check if the given page is saveable.
>   *
>   * Determine whether a non-highmem page should be included in a hibernation
> @@ -1440,7 +1440,7 @@ static inline bool do_copy_page(long *dst, long *src)
>         return !z;
>  }
>
> -/**
> +/*
>   * safe_copy_page - Copy a page in a safe way.
>   *
>   * Check if the page we are going to copy is marked as present in the kernel
> @@ -1687,7 +1687,7 @@ static unsigned long preallocate_image_highmem(unsigned long nr_pages)
>         return preallocate_image_pages(nr_pages, GFP_IMAGE | __GFP_HIGHMEM);
>  }
>
> -/**
> +/*
>   *  __fraction - Compute (an approximation of) x * (multiplier / base).
>   */
>  static unsigned long __fraction(u64 x, u64 multiplier, u64 base)
> @@ -1982,7 +1982,7 @@ int hibernate_preallocate_memory(void)
>  }
>
>  #ifdef CONFIG_HIGHMEM
> -/**
> +/*
>   * count_pages_for_highmem - Count non-highmem pages needed for copying highmem.
>   *
>   * Compute the number of non-highmem pages that will be necessary for creating
> @@ -2003,7 +2003,7 @@ static unsigned int count_pages_for_highmem(unsigned int nr_highmem)
>  static unsigned int count_pages_for_highmem(unsigned int nr_highmem) { return 0; }
>  #endif /* CONFIG_HIGHMEM */
>
> -/**
> +/*
>   * enough_free_mem - Check if there is enough free memory for the image.
>   */
>  static int enough_free_mem(unsigned int nr_pages, unsigned int nr_highmem)
> @@ -2023,7 +2023,7 @@ static int enough_free_mem(unsigned int nr_pages, unsigned int nr_highmem)
>  }
>
>  #ifdef CONFIG_HIGHMEM
> -/**
> +/*
>   * get_highmem_buffer - Allocate a buffer for highmem pages.
>   *
>   * If there are some highmem pages in the hibernation image, we may need a
> @@ -2035,7 +2035,7 @@ static inline int get_highmem_buffer(int safe_needed)
>         return buffer ? 0 : -ENOMEM;
>  }
>
> -/**
> +/*
>   * alloc_highmem_pages - Allocate some highmem pages for the image.
>   *
>   * Try to allocate as many pages as needed, but if the number of free highmem
> @@ -2065,7 +2065,7 @@ static inline unsigned int alloc_highmem_pages(struct memory_bitmap *bm,
>                                                unsigned int n) { return 0; }
>  #endif /* CONFIG_HIGHMEM */
>
> -/**
> +/*
>   * swsusp_alloc - Allocate memory for hibernation image.
>   *
>   * We first try to allocate as many highmem pages as there are
> @@ -2292,7 +2292,7 @@ static void duplicate_memory_bitmap(struct memory_bitmap *dst,
>         }
>  }
>
> -/**
> +/*
>   * mark_unsafe_pages - Mark pages that were used before hibernation.
>   *
>   * Mark the pages that cannot be used for storing the image during restoration,
> @@ -2330,7 +2330,7 @@ static int check_header(struct swsusp_info *info)
>         return 0;
>  }
>
> -/**
> +/*
>   * load_header - Check the image header and copy the data from it.
>   */
>  static int load_header(struct swsusp_info *info)
> @@ -2483,7 +2483,7 @@ static int prepare_highmem_image(struct memory_bitmap *bm,
>
>  static struct page *last_highmem_page;
>
> -/**
> +/*
>   * get_highmem_page_buffer - Prepare a buffer to store a highmem image page.
>   *
>   * For a given highmem image page get a buffer that suspend_write_next() should
> @@ -2706,7 +2706,7 @@ static int prepare_image(struct memory_bitmap *new_bm, struct memory_bitmap *bm,
>         return error;
>  }
>
> -/**
> +/*
>   * get_buffer - Get the address to store the next image data page.
>   *
>   * Get the address that snapshot_write_next() should return to its caller to
> @@ -2843,7 +2843,7 @@ int snapshot_write_next(struct snapshot_handle *handle)
>         return PAGE_SIZE;
>  }
>
> -/**
> +/*
>   * snapshot_write_finalize - Complete the loading of a hibernation image.
>   *
>   * Must be called after the last call to snapshot_write_next() in case the last
> --

Applied (under a modified subject) as 7.3 material, thanks!