power: swap: Fix comment style and clean up outdated function headers

[PATCH v3] power: swap: Fix comment style and clean up outdated function headers

Posted by Sunday Adelodun 2 months, 3 weeks ago

Several static functions in kernel/power/swap.c were written using the
kernel-doc comment style (/** ... */) even though they are not exported
or referenced by generated documentation. This led to kernel-doc warnings
and stylistic inconsistencies.

Convert these unnecessary kernel-doc blocks to regular C comments,
remove comment blocks that are no longer useful, relocate comments to
more appropriate positions where needed, and fix a few "Return:"
descriptions that were either missing or incorrectly formatted.

No functional changes.

Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
---
changelog:

Changes from v2:
- Moved the swsusp_swap_check() comment inside the function as requested.
- Dropped comment blocks that no longer provided meaningful value.
- Removed unnecessary blank lines before function definitions.
- Reformatted multi-line Return: descriptions into a single line where appropriate.
- Kept only useful non-kernel-doc comments consistent with style guidelines.

Changes from v1:
- Converted /** */ kernel-doc style blocks to /* */ regular comments.
- Cleaned up indentation and spacing.

link to v2:
https://lore.kernel.org/all/20251113110914.44223-1-adelodunolaoluwa@yahoo.com/

 kernel/power/swap.c | 58 ++++++++++-----------------------------------
 1 file changed, 12 insertions(+), 46 deletions(-)

diff --git a/kernel/power/swap.c b/kernel/power/swap.c
index 0beff7eeaaba..cf5736aabb39 100644
--- a/kernel/power/swap.c
+++ b/kernel/power/swap.c
@@ -336,16 +336,14 @@ static int mark_swapfiles(struct swap_map_handle *handle, unsigned int flags)
  */
 unsigned int swsusp_header_flags;
 
-/**
- *	swsusp_swap_check - check if the resume device is a swap device
- *	and get its index (if so)
- *
- *	This is called before saving image
- */
 static int swsusp_swap_check(void)
 {
 	int res;
 
+	/*
+	 * check if the resume device is a swap device and get its index (if so).
+	 * This is called before saving image
+	 */
 	if (swsusp_resume_device)
 		res = swap_type_of(swsusp_resume_device, swsusp_resume_block);
 	else
@@ -362,13 +360,6 @@ static int swsusp_swap_check(void)
 	return 0;
 }
 
-/**
- *	write_page - Write one page to given swap location.
- *	@buf:		Address we're writing.
- *	@offset:	Offset of the swap page we're writing to.
- *	@hb:		bio completion batch
- */
-
 static int write_page(void *buf, sector_t offset, struct hib_bio_batch *hb)
 {
 	gfp_t gfp = GFP_NOIO | __GFP_NOWARN | __GFP_NORETRY;
@@ -526,10 +517,6 @@ static int swap_writer_finish(struct swap_map_handle *handle,
 #define CMP_MIN_RD_PAGES	1024
 #define CMP_MAX_RD_PAGES	8192
 
-/**
- *	save_image - save the suspend image data
- */
-
 static int save_image(struct swap_map_handle *handle,
                       struct snapshot_handle *snapshot,
                       unsigned int nr_to_write)
@@ -671,12 +658,6 @@ static int compress_threadfn(void *data)
 	return 0;
 }
 
-/**
- * save_compressed_image - Save the suspend image data after compression.
- * @handle: Swap map handle to use for saving the image.
- * @snapshot: Image to read data from.
- * @nr_to_write: Number of pages to save.
- */
 static int save_compressed_image(struct swap_map_handle *handle,
 				 struct snapshot_handle *snapshot,
 				 unsigned int nr_to_write)
@@ -904,13 +885,6 @@ static int save_compressed_image(struct swap_map_handle *handle,
 	return ret;
 }
 
-/**
- *	enough_swap - Make sure we have enough swap to save the image.
- *
- *	Returns TRUE or FALSE after checking the total amount of swap
- *	space available from the resume partition.
- */
-
 static int enough_swap(unsigned int nr_pages)
 {
 	unsigned int free_swap = count_swap_pages(root_swap, 1);
@@ -930,8 +904,9 @@ static int enough_swap(unsigned int nr_pages)
  *	them synced (in case something goes wrong) but we DO not want to mark
  *	filesystem clean: it is not. (And it does not matter, if we resume
  *	correctly, we'll mark system clean, anyway.)
+ *
+ *	Return: 0 on success, negative error code on failure.
  */
-
 int swsusp_write(unsigned int flags)
 {
 	struct swap_map_handle handle;
@@ -1077,12 +1052,6 @@ static int swap_reader_finish(struct swap_map_handle *handle)
 	return 0;
 }
 
-/**
- *	load_image - load the image using the swap map handle
- *	@handle and the snapshot handle @snapshot
- *	(assume there are @nr_pages pages to load)
- */
-
 static int load_image(struct swap_map_handle *handle,
                       struct snapshot_handle *snapshot,
                       unsigned int nr_to_read)
@@ -1190,12 +1159,6 @@ static int decompress_threadfn(void *data)
 	return 0;
 }
 
-/**
- * load_compressed_image - Load compressed image data and decompress it.
- * @handle: Swap map handle to use for loading data.
- * @snapshot: Image to copy uncompressed data into.
- * @nr_to_read: Number of pages to load.
- */
 static int load_compressed_image(struct swap_map_handle *handle,
 				 struct snapshot_handle *snapshot,
 				 unsigned int nr_to_read)
@@ -1529,8 +1492,9 @@ static int load_compressed_image(struct swap_map_handle *handle,
  *	swsusp_read - read the hibernation image.
  *	@flags_p: flags passed by the "frozen" kernel in the image header should
  *		  be written into this memory location
+ *
+ *	Return: 0 on success, negative error code on failure.
  */
-
 int swsusp_read(unsigned int *flags_p)
 {
 	int error;
@@ -1567,8 +1531,9 @@ static void *swsusp_holder;
 /**
  * swsusp_check - Open the resume device and check for the swsusp signature.
  * @exclusive: Open the resume device exclusively.
+ *
+ * Return: 0 if a valid hibernation image is found, negative error code on failure.
  */
-
 int swsusp_check(bool exclusive)
 {
 	void *holder = exclusive ? &swsusp_holder : NULL;
@@ -1631,8 +1596,9 @@ void swsusp_close(void)
 
 /**
  *      swsusp_unmark - Unmark swsusp signature in the resume device
+ *
+ *      Return: 0 on success, negative error code on failure.
  */
-
 #ifdef CONFIG_SUSPEND
 int swsusp_unmark(void)
 {
-- 
2.43.0

Re: [PATCH v3] power: swap: Fix comment style and clean up outdated function headers

Posted by Rafael J. Wysocki 2 months, 3 weeks ago

On Fri, Nov 14, 2025 at 11:04 PM Sunday Adelodun
<adelodunolaoluwa@yahoo.com> wrote:
>
> Several static functions in kernel/power/swap.c were written using the
> kernel-doc comment style (/** ... */) even though they are not exported
> or referenced by generated documentation. This led to kernel-doc warnings
> and stylistic inconsistencies.
>
> Convert these unnecessary kernel-doc blocks to regular C comments,
> remove comment blocks that are no longer useful, relocate comments to
> more appropriate positions where needed, and fix a few "Return:"
> descriptions that were either missing or incorrectly formatted.
>
> No functional changes.
>
> Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
> ---
> changelog:
>
> Changes from v2:
> - Moved the swsusp_swap_check() comment inside the function as requested.
> - Dropped comment blocks that no longer provided meaningful value.
> - Removed unnecessary blank lines before function definitions.
> - Reformatted multi-line Return: descriptions into a single line where appropriate.
> - Kept only useful non-kernel-doc comments consistent with style guidelines.
>
> Changes from v1:
> - Converted /** */ kernel-doc style blocks to /* */ regular comments.
> - Cleaned up indentation and spacing.
>
> link to v2:
> https://lore.kernel.org/all/20251113110914.44223-1-adelodunolaoluwa@yahoo.com/
>
>  kernel/power/swap.c | 58 ++++++++++-----------------------------------
>  1 file changed, 12 insertions(+), 46 deletions(-)
>
> diff --git a/kernel/power/swap.c b/kernel/power/swap.c
> index 0beff7eeaaba..cf5736aabb39 100644
> --- a/kernel/power/swap.c
> +++ b/kernel/power/swap.c
> @@ -336,16 +336,14 @@ static int mark_swapfiles(struct swap_map_handle *handle, unsigned int flags)
>   */
>  unsigned int swsusp_header_flags;
>
> -/**
> - *     swsusp_swap_check - check if the resume device is a swap device
> - *     and get its index (if so)
> - *
> - *     This is called before saving image
> - */
>  static int swsusp_swap_check(void)
>  {
>         int res;
>
> +       /*
> +        * check if the resume device is a swap device and get its index (if so).
> +        * This is called before saving image
> +        */
>         if (swsusp_resume_device)
>                 res = swap_type_of(swsusp_resume_device, swsusp_resume_block);
>         else
> @@ -362,13 +360,6 @@ static int swsusp_swap_check(void)
>         return 0;
>  }
>
> -/**
> - *     write_page - Write one page to given swap location.
> - *     @buf:           Address we're writing.
> - *     @offset:        Offset of the swap page we're writing to.
> - *     @hb:            bio completion batch
> - */
> -
>  static int write_page(void *buf, sector_t offset, struct hib_bio_batch *hb)
>  {
>         gfp_t gfp = GFP_NOIO | __GFP_NOWARN | __GFP_NORETRY;
> @@ -526,10 +517,6 @@ static int swap_writer_finish(struct swap_map_handle *handle,
>  #define CMP_MIN_RD_PAGES       1024
>  #define CMP_MAX_RD_PAGES       8192
>
> -/**
> - *     save_image - save the suspend image data
> - */
> -
>  static int save_image(struct swap_map_handle *handle,
>                        struct snapshot_handle *snapshot,
>                        unsigned int nr_to_write)
> @@ -671,12 +658,6 @@ static int compress_threadfn(void *data)
>         return 0;
>  }
>
> -/**
> - * save_compressed_image - Save the suspend image data after compression.
> - * @handle: Swap map handle to use for saving the image.
> - * @snapshot: Image to read data from.
> - * @nr_to_write: Number of pages to save.
> - */
>  static int save_compressed_image(struct swap_map_handle *handle,
>                                  struct snapshot_handle *snapshot,
>                                  unsigned int nr_to_write)
> @@ -904,13 +885,6 @@ static int save_compressed_image(struct swap_map_handle *handle,
>         return ret;
>  }
>
> -/**
> - *     enough_swap - Make sure we have enough swap to save the image.
> - *
> - *     Returns TRUE or FALSE after checking the total amount of swap
> - *     space available from the resume partition.
> - */
> -
>  static int enough_swap(unsigned int nr_pages)
>  {
>         unsigned int free_swap = count_swap_pages(root_swap, 1);
> @@ -930,8 +904,9 @@ static int enough_swap(unsigned int nr_pages)
>   *     them synced (in case something goes wrong) but we DO not want to mark
>   *     filesystem clean: it is not. (And it does not matter, if we resume
>   *     correctly, we'll mark system clean, anyway.)
> + *
> + *     Return: 0 on success, negative error code on failure.
>   */
> -
>  int swsusp_write(unsigned int flags)
>  {
>         struct swap_map_handle handle;
> @@ -1077,12 +1052,6 @@ static int swap_reader_finish(struct swap_map_handle *handle)
>         return 0;
>  }
>
> -/**
> - *     load_image - load the image using the swap map handle
> - *     @handle and the snapshot handle @snapshot
> - *     (assume there are @nr_pages pages to load)
> - */
> -
>  static int load_image(struct swap_map_handle *handle,
>                        struct snapshot_handle *snapshot,
>                        unsigned int nr_to_read)
> @@ -1190,12 +1159,6 @@ static int decompress_threadfn(void *data)
>         return 0;
>  }
>
> -/**
> - * load_compressed_image - Load compressed image data and decompress it.
> - * @handle: Swap map handle to use for loading data.
> - * @snapshot: Image to copy uncompressed data into.
> - * @nr_to_read: Number of pages to load.
> - */
>  static int load_compressed_image(struct swap_map_handle *handle,
>                                  struct snapshot_handle *snapshot,
>                                  unsigned int nr_to_read)
> @@ -1529,8 +1492,9 @@ static int load_compressed_image(struct swap_map_handle *handle,
>   *     swsusp_read - read the hibernation image.
>   *     @flags_p: flags passed by the "frozen" kernel in the image header should
>   *               be written into this memory location
> + *
> + *     Return: 0 on success, negative error code on failure.
>   */
> -
>  int swsusp_read(unsigned int *flags_p)
>  {
>         int error;
> @@ -1567,8 +1531,9 @@ static void *swsusp_holder;
>  /**
>   * swsusp_check - Open the resume device and check for the swsusp signature.
>   * @exclusive: Open the resume device exclusively.
> + *
> + * Return: 0 if a valid hibernation image is found, negative error code on failure.
>   */
> -
>  int swsusp_check(bool exclusive)
>  {
>         void *holder = exclusive ? &swsusp_holder : NULL;
> @@ -1631,8 +1596,9 @@ void swsusp_close(void)
>
>  /**
>   *      swsusp_unmark - Unmark swsusp signature in the resume device
> + *
> + *      Return: 0 on success, negative error code on failure.
>   */
> -
>  #ifdef CONFIG_SUSPEND
>  int swsusp_unmark(void)
>  {
> --

Applied as 6.19 material with some edits in the subject, changelog,
and updated code comments.

Thanks!