mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
* [PATCH 0/2] Fix kernel-doc warnings in power and time
       [not found] <20251106113938.34693-1-adelodunolaoluwa.ref@yahoo.com>
@ 2025-11-06 11:39 ` Sunday Adelodun
  2025-11-06 11:39   ` [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments Sunday Adelodun
  2025-11-06 11:39   ` [PATCH 2/2] time: tick-oneshot: add missing Return: and param descriptions to kernel-doc Sunday Adelodun
  0 siblings, 2 replies; 7+ messages in thread
From: Sunday Adelodun @ 2025-11-06 11:39 UTC (permalink / raw)
  To: rafael, lenb, pavel, anna-maria, frederic, mingo, tglx
  Cc: linux-pm, linux-kernel, Sunday Adelodun

Hi,

This small patch series fixes kernel-doc warnings in kernel/power/swap.c
and kernel/time/tick-oneshot.c by adding missing parameter and return
value descriptions. These changes improve documentation clarity and
remove "No description found for return value" warnings during doc
build.

No functional changes.

Patches:
  1/2 power/swap: add missing params and Return: descriptions to kernel-doc
                  comments
  2/2 time/tick-oneshot: add missing Return: and param descriptions to
                         kernel-doc

Thanks,
Sunday Adelodun

Sunday Adelodun (2):
  power/swap: add missing params and Return: descriptions to kernel-doc
    comments
  time: tick-oneshot: add missing Return: and param descriptions to 
    kernel-doc

 kernel/power/swap.c        | 35 +++++++++++++++++++++++++++++++----
 kernel/time/tick-oneshot.c | 20 +++++++++++++++++++-
 2 files changed, 50 insertions(+), 5 deletions(-)

-- 
2.43.0


^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments
  2025-11-06 11:39 ` [PATCH 0/2] Fix kernel-doc warnings in power and time Sunday Adelodun
@ 2025-11-06 11:39   ` Sunday Adelodun
  2025-11-07 15:36     ` Rafael J. Wysocki
  2025-11-06 11:39   ` [PATCH 2/2] time: tick-oneshot: add missing Return: and param descriptions to kernel-doc Sunday Adelodun
  1 sibling, 1 reply; 7+ messages in thread
From: Sunday Adelodun @ 2025-11-06 11:39 UTC (permalink / raw)
  To: rafael, lenb, pavel, anna-maria, frederic, mingo, tglx
  Cc: linux-pm, linux-kernel, Sunday Adelodun

Kernel-doc checks (scripts/kernel-doc) reported a number of warnings
for missing parameters and `Return:` descriptions in kernel/power/swap.c.
These missing return descriptions make the generated documentation
noisy and break doc-build when -Werror is used.

Update the kernel-doc comment blocks to add explicit
Return: lines (and a few parameter tags where helpful) for the functions
that were triggering warnings. No functional code changes are made.

Example warnings that motivated this change:
 - Warning: kernel/power/swap.c:535 No description found for return value
   of 'save_image'
 - Warning: kernel/power/swap.c:687 No description found for return value
  of 'save_compressed_image'
 - Warning: kernel/power/swap.c:941 No description found for return value
   of 'swsusp_write'

Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
---
 kernel/power/swap.c | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/kernel/power/swap.c b/kernel/power/swap.c
index 0beff7eeaaba..3f0df7a26bc3 100644
--- a/kernel/power/swap.c
+++ b/kernel/power/swap.c
@@ -341,6 +341,8 @@ unsigned int swsusp_header_flags;
  *	and get its index (if so)
  *
  *	This is called before saving image
+ *
+ *	Return: 0 on success, negative error code on failure.
  */
 static int swsusp_swap_check(void)
 {
@@ -367,6 +369,8 @@ static int swsusp_swap_check(void)
  *	@buf:		Address we're writing.
  *	@offset:	Offset of the swap page we're writing to.
  *	@hb:		bio completion batch
+ *
+ *	Return: 0 on success, negative error code on failure.
  */
 
 static int write_page(void *buf, sector_t offset, struct hib_bio_batch *hb)
@@ -528,6 +532,11 @@ static int swap_writer_finish(struct swap_map_handle *handle,
 
 /**
  *	save_image - save the suspend image data
+ *	@handle: swap map handle for writing the image
+ *	@snapshot: snapshot handle to read pages from
+ *	@nr_to_write: number of pages to write
+ *
+ *	Return: 0 on success, negative error on failure
  */
 
 static int save_image(struct swap_map_handle *handle,
@@ -676,6 +685,8 @@ static int compress_threadfn(void *data)
  * @handle: Swap map handle to use for saving the image.
  * @snapshot: Image to read data from.
  * @nr_to_write: Number of pages to save.
+ *
+ * Return: 0 on success, negative error code on failure.
  */
 static int save_compressed_image(struct swap_map_handle *handle,
 				 struct snapshot_handle *snapshot,
@@ -906,8 +917,9 @@ static int save_compressed_image(struct swap_map_handle *handle,
 
 /**
  *	enough_swap - Make sure we have enough swap to save the image.
+ *	@nr_pages: number of pages we need to save
  *
- *	Returns TRUE or FALSE after checking the total amount of swap
+ *	Return: TRUE or FALSE after checking the total amount of swap
  *	space available from the resume partition.
  */
 
@@ -930,6 +942,8 @@ 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)
@@ -1078,9 +1092,12 @@ static int swap_reader_finish(struct swap_map_handle *handle)
 }
 
 /**
- *	load_image - load the image using the swap map handle
- *	@handle and the snapshot handle @snapshot
- *	(assume there are @nr_pages pages to load)
+ *	load_image - load the image using the swap map and snapshot handles
+ *	@handle: pointer to the swap map used for reading swap pages
+ *	@snapshot: pointer to the snapshot handle that tracks image pages
+ *	@nr_to_read: number of pages to read from the snapshot
+ *
+ *	Return: 0 on success, negative error code on failure.
  */
 
 static int load_image(struct swap_map_handle *handle,
@@ -1195,6 +1212,8 @@ static int decompress_threadfn(void *data)
  * @handle: Swap map handle to use for loading data.
  * @snapshot: Image to copy uncompressed data into.
  * @nr_to_read: Number of pages to load.
+ *
+ * Return: 0 on success, negative error code on failure.
  */
 static int load_compressed_image(struct swap_map_handle *handle,
 				 struct snapshot_handle *snapshot,
@@ -1529,6 +1548,8 @@ 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)
@@ -1567,6 +1588,10 @@ 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)
@@ -1631,6 +1656,8 @@ 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
-- 
2.43.0


^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH 2/2] time: tick-oneshot: add missing Return: and param descriptions to  kernel-doc
  2025-11-06 11:39 ` [PATCH 0/2] Fix kernel-doc warnings in power and time Sunday Adelodun
  2025-11-06 11:39   ` [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments Sunday Adelodun
@ 2025-11-06 11:39   ` Sunday Adelodun
  2025-11-14 19:21     ` [tip: timers/core] time: tick-oneshot: Add missing Return and parameter " tip-bot2 for Sunday Adelodun
  1 sibling, 1 reply; 7+ messages in thread
From: Sunday Adelodun @ 2025-11-06 11:39 UTC (permalink / raw)
  To: rafael, lenb, pavel, anna-maria, frederic, mingo, tglx
  Cc: linux-pm, linux-kernel, Sunday Adelodun

Several functions in kernel/time/tick-oneshot.c were missing parameter
and return value descriptions in their kernel-doc comments. This caused
warnings during doc generation.

Update the kernel-doc blocks to include detailed @param and
Return: descriptions for better clarity and to fix kernel-doc warnings.
No functional code changes are made.

Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
---
 kernel/time/tick-oneshot.c | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/kernel/time/tick-oneshot.c b/kernel/time/tick-oneshot.c
index 5e2c2c26b3cc..ffee943d796d 100644
--- a/kernel/time/tick-oneshot.c
+++ b/kernel/time/tick-oneshot.c
@@ -19,6 +19,10 @@
 
 /**
  * tick_program_event - program the CPU local timer device for the next event
+ * @expires: the time at which the next timer event should occur
+ * @force: flag to force reprograming even if the event time hasn't changed
+ *
+ * Return: 0 on success, negative error code on failure
  */
 int tick_program_event(ktime_t expires, int force)
 {
@@ -57,6 +61,13 @@ void tick_resume_oneshot(void)
 
 /**
  * tick_setup_oneshot - setup the event device for oneshot mode (hres or nohz)
+ * @newdev: Pointer to the clock event device to configure
+ * @handler: Function to be called when the event device triggers an interrupt
+ * @next_event: Initial expiry time for the next event (in ktime)
+ *
+ * Configures the specified clock event device for onshot mode,
+ * assigns the given handler as its event callback, and programs
+ * the device to trigger at the specified next event time.
  */
 void tick_setup_oneshot(struct clock_event_device *newdev,
 			void (*handler)(struct clock_event_device *),
@@ -69,6 +80,10 @@ void tick_setup_oneshot(struct clock_event_device *newdev,
 
 /**
  * tick_switch_to_oneshot - switch to oneshot mode
+ * @handler: function to call when an event occurs on the tick device
+ *
+ * Return: 0 on success, -EINVAL if the tick device is not present,
+ *         not functional, or does not support oneshot mode.
  */
 int tick_switch_to_oneshot(void (*handler)(struct clock_event_device *))
 {
@@ -101,7 +116,7 @@ int tick_switch_to_oneshot(void (*handler)(struct clock_event_device *))
 /**
  * tick_oneshot_mode_active - check whether the system is in oneshot mode
  *
- * returns 1 when either nohz or highres are enabled. otherwise 0.
+ * Return: 1 when either nohz or highres are enabled, otherwise 0.
  */
 int tick_oneshot_mode_active(void)
 {
@@ -120,6 +135,9 @@ int tick_oneshot_mode_active(void)
  * tick_init_highres - switch to high resolution mode
  *
  * Called with interrupts disabled.
+ *
+ * Return: 0 on success, -EINVAL if the tick device cannot switch
+ *         to oneshot/high-resolution mode.
  */
 int tick_init_highres(void)
 {
-- 
2.43.0


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments
  2025-11-06 11:39   ` [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments Sunday Adelodun
@ 2025-11-07 15:36     ` Rafael J. Wysocki
  2025-11-07 19:58       ` Sunday Adelodun
  0 siblings, 1 reply; 7+ messages in thread
From: Rafael J. Wysocki @ 2025-11-07 15:36 UTC (permalink / raw)
  To: Sunday Adelodun
  Cc: rafael, lenb, pavel, anna-maria, frederic, mingo, tglx, linux-pm,
	linux-kernel

On Thu, Nov 6, 2025 at 12:40 PM Sunday Adelodun
<adelodunolaoluwa@yahoo.com> wrote:
>
> Kernel-doc checks (scripts/kernel-doc) reported a number of warnings
> for missing parameters and `Return:` descriptions in kernel/power/swap.c.
> These missing return descriptions make the generated documentation
> noisy and break doc-build when -Werror is used.
>
> Update the kernel-doc comment blocks to add explicit
> Return: lines (and a few parameter tags where helpful) for the functions
> that were triggering warnings. No functional code changes are made.
>
> Example warnings that motivated this change:
>  - Warning: kernel/power/swap.c:535 No description found for return value
>    of 'save_image'
>  - Warning: kernel/power/swap.c:687 No description found for return value
>   of 'save_compressed_image'
>  - Warning: kernel/power/swap.c:941 No description found for return value
>    of 'swsusp_write'
>
> Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>

These comments need more changes to become proper kerneldocs and in
some cases it is not even necessary because the functions in question
are static.

If the goal is to avoid warnings, why don't you change them all to
non-kerneldoc regular comments?

> ---
>  kernel/power/swap.c | 35 +++++++++++++++++++++++++++++++----
>  1 file changed, 31 insertions(+), 4 deletions(-)
>
> diff --git a/kernel/power/swap.c b/kernel/power/swap.c
> index 0beff7eeaaba..3f0df7a26bc3 100644
> --- a/kernel/power/swap.c
> +++ b/kernel/power/swap.c
> @@ -341,6 +341,8 @@ unsigned int swsusp_header_flags;
>   *     and get its index (if so)
>   *
>   *     This is called before saving image
> + *
> + *     Return: 0 on success, negative error code on failure.
>   */
>  static int swsusp_swap_check(void)
>  {
> @@ -367,6 +369,8 @@ static int swsusp_swap_check(void)
>   *     @buf:           Address we're writing.
>   *     @offset:        Offset of the swap page we're writing to.
>   *     @hb:            bio completion batch
> + *
> + *     Return: 0 on success, negative error code on failure.
>   */
>
>  static int write_page(void *buf, sector_t offset, struct hib_bio_batch *hb)
> @@ -528,6 +532,11 @@ static int swap_writer_finish(struct swap_map_handle *handle,
>
>  /**
>   *     save_image - save the suspend image data
> + *     @handle: swap map handle for writing the image
> + *     @snapshot: snapshot handle to read pages from
> + *     @nr_to_write: number of pages to write
> + *
> + *     Return: 0 on success, negative error on failure
>   */
>
>  static int save_image(struct swap_map_handle *handle,
> @@ -676,6 +685,8 @@ static int compress_threadfn(void *data)
>   * @handle: Swap map handle to use for saving the image.
>   * @snapshot: Image to read data from.
>   * @nr_to_write: Number of pages to save.
> + *
> + * Return: 0 on success, negative error code on failure.
>   */
>  static int save_compressed_image(struct swap_map_handle *handle,
>                                  struct snapshot_handle *snapshot,
> @@ -906,8 +917,9 @@ static int save_compressed_image(struct swap_map_handle *handle,
>
>  /**
>   *     enough_swap - Make sure we have enough swap to save the image.
> + *     @nr_pages: number of pages we need to save
>   *
> - *     Returns TRUE or FALSE after checking the total amount of swap
> + *     Return: TRUE or FALSE after checking the total amount of swap
>   *     space available from the resume partition.
>   */
>
> @@ -930,6 +942,8 @@ 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)
> @@ -1078,9 +1092,12 @@ static int swap_reader_finish(struct swap_map_handle *handle)
>  }
>
>  /**
> - *     load_image - load the image using the swap map handle
> - *     @handle and the snapshot handle @snapshot
> - *     (assume there are @nr_pages pages to load)
> + *     load_image - load the image using the swap map and snapshot handles
> + *     @handle: pointer to the swap map used for reading swap pages
> + *     @snapshot: pointer to the snapshot handle that tracks image pages
> + *     @nr_to_read: number of pages to read from the snapshot
> + *
> + *     Return: 0 on success, negative error code on failure.
>   */
>
>  static int load_image(struct swap_map_handle *handle,
> @@ -1195,6 +1212,8 @@ static int decompress_threadfn(void *data)
>   * @handle: Swap map handle to use for loading data.
>   * @snapshot: Image to copy uncompressed data into.
>   * @nr_to_read: Number of pages to load.
> + *
> + * Return: 0 on success, negative error code on failure.
>   */
>  static int load_compressed_image(struct swap_map_handle *handle,
>                                  struct snapshot_handle *snapshot,
> @@ -1529,6 +1548,8 @@ 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)
> @@ -1567,6 +1588,10 @@ 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)
> @@ -1631,6 +1656,8 @@ 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
> --
> 2.43.0
>

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments
  2025-11-07 15:36     ` Rafael J. Wysocki
@ 2025-11-07 19:58       ` Sunday Adelodun
  2025-11-07 20:19         ` Rafael J. Wysocki
  0 siblings, 1 reply; 7+ messages in thread
From: Sunday Adelodun @ 2025-11-07 19:58 UTC (permalink / raw)
  To: Rafael J. Wysocki
  Cc: lenb, pavel, anna-maria, frederic, mingo, tglx, linux-pm, linux-kernel

On 11/7/25 16:36, Rafael J. Wysocki wrote:
> On Thu, Nov 6, 2025 at 12:40 PM Sunday Adelodun
> <adelodunolaoluwa@yahoo.com> wrote:
>> Kernel-doc checks (scripts/kernel-doc) reported a number of warnings
>> for missing parameters and `Return:` descriptions in kernel/power/swap.c.
>> These missing return descriptions make the generated documentation
>> noisy and break doc-build when -Werror is used.
>>
>> Update the kernel-doc comment blocks to add explicit
>> Return: lines (and a few parameter tags where helpful) for the functions
>> that were triggering warnings. No functional code changes are made.
>>
>> Example warnings that motivated this change:
>>   - Warning: kernel/power/swap.c:535 No description found for return value
>>     of 'save_image'
>>   - Warning: kernel/power/swap.c:687 No description found for return value
>>    of 'save_compressed_image'
>>   - Warning: kernel/power/swap.c:941 No description found for return value
>>     of 'swsusp_write'
>>
>> Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
> These comments need more changes to become proper kerneldocs and in
> some cases it is not even necessary because the functions in question
> are static.
>
> If the goal is to avoid warnings, why don't you change them all to
> non-kerneldoc regular comments?

Thank you very much for the feedback.

For the functions that are not static, could you please suggest the 
appropriate changes

needed to make their comments proper? I would like to improve them 
accordingly.

My initial goal was to address the warnings, but if converting them to 
regular comments

is the preferred approach, I will go ahead and update them that way in v2.

Thanks again for your guidance.

Best,
Sunday Adelodun

>
>> ---
>>   kernel/power/swap.c | 35 +++++++++++++++++++++++++++++++----
>>   1 file changed, 31 insertions(+), 4 deletions(-)
>>
>> diff --git a/kernel/power/swap.c b/kernel/power/swap.c
>> index 0beff7eeaaba..3f0df7a26bc3 100644
>> --- a/kernel/power/swap.c
>> +++ b/kernel/power/swap.c
>> @@ -341,6 +341,8 @@ unsigned int swsusp_header_flags;
>>    *     and get its index (if so)
>>    *
>>    *     This is called before saving image
>> + *
>> + *     Return: 0 on success, negative error code on failure.
>>    */
>>   static int swsusp_swap_check(void)
>>   {
>> @@ -367,6 +369,8 @@ static int swsusp_swap_check(void)
>>    *     @buf:           Address we're writing.
>>    *     @offset:        Offset of the swap page we're writing to.
>>    *     @hb:            bio completion batch
>> + *
>> + *     Return: 0 on success, negative error code on failure.
>>    */
>>
>>   static int write_page(void *buf, sector_t offset, struct hib_bio_batch *hb)
>> @@ -528,6 +532,11 @@ static int swap_writer_finish(struct swap_map_handle *handle,
>>
>>   /**
>>    *     save_image - save the suspend image data
>> + *     @handle: swap map handle for writing the image
>> + *     @snapshot: snapshot handle to read pages from
>> + *     @nr_to_write: number of pages to write
>> + *
>> + *     Return: 0 on success, negative error on failure
>>    */
>>
>>   static int save_image(struct swap_map_handle *handle,
>> @@ -676,6 +685,8 @@ static int compress_threadfn(void *data)
>>    * @handle: Swap map handle to use for saving the image.
>>    * @snapshot: Image to read data from.
>>    * @nr_to_write: Number of pages to save.
>> + *
>> + * Return: 0 on success, negative error code on failure.
>>    */
>>   static int save_compressed_image(struct swap_map_handle *handle,
>>                                   struct snapshot_handle *snapshot,
>> @@ -906,8 +917,9 @@ static int save_compressed_image(struct swap_map_handle *handle,
>>
>>   /**
>>    *     enough_swap - Make sure we have enough swap to save the image.
>> + *     @nr_pages: number of pages we need to save
>>    *
>> - *     Returns TRUE or FALSE after checking the total amount of swap
>> + *     Return: TRUE or FALSE after checking the total amount of swap
>>    *     space available from the resume partition.
>>    */
>>
>> @@ -930,6 +942,8 @@ 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)
>> @@ -1078,9 +1092,12 @@ static int swap_reader_finish(struct swap_map_handle *handle)
>>   }
>>
>>   /**
>> - *     load_image - load the image using the swap map handle
>> - *     @handle and the snapshot handle @snapshot
>> - *     (assume there are @nr_pages pages to load)
>> + *     load_image - load the image using the swap map and snapshot handles
>> + *     @handle: pointer to the swap map used for reading swap pages
>> + *     @snapshot: pointer to the snapshot handle that tracks image pages
>> + *     @nr_to_read: number of pages to read from the snapshot
>> + *
>> + *     Return: 0 on success, negative error code on failure.
>>    */
>>
>>   static int load_image(struct swap_map_handle *handle,
>> @@ -1195,6 +1212,8 @@ static int decompress_threadfn(void *data)
>>    * @handle: Swap map handle to use for loading data.
>>    * @snapshot: Image to copy uncompressed data into.
>>    * @nr_to_read: Number of pages to load.
>> + *
>> + * Return: 0 on success, negative error code on failure.
>>    */
>>   static int load_compressed_image(struct swap_map_handle *handle,
>>                                   struct snapshot_handle *snapshot,
>> @@ -1529,6 +1548,8 @@ 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)
>> @@ -1567,6 +1588,10 @@ 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)
>> @@ -1631,6 +1656,8 @@ 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
>> --
>> 2.43.0
>>


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments
  2025-11-07 19:58       ` Sunday Adelodun
@ 2025-11-07 20:19         ` Rafael J. Wysocki
  0 siblings, 0 replies; 7+ messages in thread
From: Rafael J. Wysocki @ 2025-11-07 20:19 UTC (permalink / raw)
  To: Sunday Adelodun
  Cc: Rafael J. Wysocki, lenb, pavel, anna-maria, frederic, mingo,
	tglx, linux-pm, linux-kernel

On Fri, Nov 7, 2025 at 9:09 PM Sunday Adelodun
<adelodunolaoluwa@yahoo.com> wrote:
>
> On 11/7/25 16:36, Rafael J. Wysocki wrote:
> > On Thu, Nov 6, 2025 at 12:40 PM Sunday Adelodun
> > <adelodunolaoluwa@yahoo.com> wrote:
> >> Kernel-doc checks (scripts/kernel-doc) reported a number of warnings
> >> for missing parameters and `Return:` descriptions in kernel/power/swap.c.
> >> These missing return descriptions make the generated documentation
> >> noisy and break doc-build when -Werror is used.
> >>
> >> Update the kernel-doc comment blocks to add explicit
> >> Return: lines (and a few parameter tags where helpful) for the functions
> >> that were triggering warnings. No functional code changes are made.
> >>
> >> Example warnings that motivated this change:
> >>   - Warning: kernel/power/swap.c:535 No description found for return value
> >>     of 'save_image'
> >>   - Warning: kernel/power/swap.c:687 No description found for return value
> >>    of 'save_compressed_image'
> >>   - Warning: kernel/power/swap.c:941 No description found for return value
> >>     of 'swsusp_write'
> >>
> >> Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
> > These comments need more changes to become proper kerneldocs and in
> > some cases it is not even necessary because the functions in question
> > are static.
> >
> > If the goal is to avoid warnings, why don't you change them all to
> > non-kerneldoc regular comments?
>
> Thank you very much for the feedback.
>
> For the functions that are not static, could you please suggest the
> appropriate changes needed to make their comments proper? I would like
> to improve them accordingly.

There are some white space changes to be made and general formatting
needs to be improved in some cases.

> My initial goal was to address the warnings, but if converting them to
> regular comments
>
> is the preferred approach, I will go ahead and update them that way in v2.

I would split this into 2 patches, one changing the comments on the
static functions to non-kerneldoc (and maybe dropping some of them
entirely) and the other changing the remaining comments into proper
kerneldoc ones.

Thanks!

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [tip: timers/core] time: tick-oneshot: Add missing Return and parameter descriptions to kernel-doc
  2025-11-06 11:39   ` [PATCH 2/2] time: tick-oneshot: add missing Return: and param descriptions to kernel-doc Sunday Adelodun
@ 2025-11-14 19:21     ` tip-bot2 for Sunday Adelodun
  0 siblings, 0 replies; 7+ messages in thread
From: tip-bot2 for Sunday Adelodun @ 2025-11-14 19:21 UTC (permalink / raw)
  To: linux-tip-commits; +Cc: Sunday Adelodun, Thomas Gleixner, x86, linux-kernel

The following commit has been merged into the timers/core branch of tip:

Commit-ID:     e54dd0474c281ebcd32ada4bdbe1e0ada2e1c22b
Gitweb:        https://git.kernel.org/tip/e54dd0474c281ebcd32ada4bdbe1e0ada2e1c22b
Author:        Sunday Adelodun <adelodunolaoluwa@yahoo.com>
AuthorDate:    Thu, 06 Nov 2025 12:39:38 +01:00
Committer:     Thomas Gleixner <tglx@linutronix.de>
CommitterDate: Fri, 14 Nov 2025 20:17:44 +01:00

time: tick-oneshot: Add missing Return and parameter descriptions to kernel-doc

Several functions in kernel/time/tick-oneshot.c are missing parameter and
return value descriptions in their kernel-doc comments. This causes
warnings during doc generation.

Update the kernel-doc blocks to include detailed @param and Return:
descriptions for better clarity and to fix kernel-doc warnings.  No
functional code changes are made.

Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Link: https://patch.msgid.link/20251106113938.34693-3-adelodunolaoluwa@yahoo.com
---
 kernel/time/tick-oneshot.c | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/kernel/time/tick-oneshot.c b/kernel/time/tick-oneshot.c
index 5e2c2c2..ffee943 100644
--- a/kernel/time/tick-oneshot.c
+++ b/kernel/time/tick-oneshot.c
@@ -19,6 +19,10 @@
 
 /**
  * tick_program_event - program the CPU local timer device for the next event
+ * @expires: the time at which the next timer event should occur
+ * @force: flag to force reprograming even if the event time hasn't changed
+ *
+ * Return: 0 on success, negative error code on failure
  */
 int tick_program_event(ktime_t expires, int force)
 {
@@ -57,6 +61,13 @@ void tick_resume_oneshot(void)
 
 /**
  * tick_setup_oneshot - setup the event device for oneshot mode (hres or nohz)
+ * @newdev: Pointer to the clock event device to configure
+ * @handler: Function to be called when the event device triggers an interrupt
+ * @next_event: Initial expiry time for the next event (in ktime)
+ *
+ * Configures the specified clock event device for onshot mode,
+ * assigns the given handler as its event callback, and programs
+ * the device to trigger at the specified next event time.
  */
 void tick_setup_oneshot(struct clock_event_device *newdev,
 			void (*handler)(struct clock_event_device *),
@@ -69,6 +80,10 @@ void tick_setup_oneshot(struct clock_event_device *newdev,
 
 /**
  * tick_switch_to_oneshot - switch to oneshot mode
+ * @handler: function to call when an event occurs on the tick device
+ *
+ * Return: 0 on success, -EINVAL if the tick device is not present,
+ *         not functional, or does not support oneshot mode.
  */
 int tick_switch_to_oneshot(void (*handler)(struct clock_event_device *))
 {
@@ -101,7 +116,7 @@ int tick_switch_to_oneshot(void (*handler)(struct clock_event_device *))
 /**
  * tick_oneshot_mode_active - check whether the system is in oneshot mode
  *
- * returns 1 when either nohz or highres are enabled. otherwise 0.
+ * Return: 1 when either nohz or highres are enabled, otherwise 0.
  */
 int tick_oneshot_mode_active(void)
 {
@@ -120,6 +135,9 @@ int tick_oneshot_mode_active(void)
  * tick_init_highres - switch to high resolution mode
  *
  * Called with interrupts disabled.
+ *
+ * Return: 0 on success, -EINVAL if the tick device cannot switch
+ *         to oneshot/high-resolution mode.
  */
 int tick_init_highres(void)
 {

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2025-11-14 19:22 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
     [not found] <20251106113938.34693-1-adelodunolaoluwa.ref@yahoo.com>
2025-11-06 11:39 ` [PATCH 0/2] Fix kernel-doc warnings in power and time Sunday Adelodun
2025-11-06 11:39   ` [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments Sunday Adelodun
2025-11-07 15:36     ` Rafael J. Wysocki
2025-11-07 19:58       ` Sunday Adelodun
2025-11-07 20:19         ` Rafael J. Wysocki
2025-11-06 11:39   ` [PATCH 2/2] time: tick-oneshot: add missing Return: and param descriptions to kernel-doc Sunday Adelodun
2025-11-14 19:21     ` [tip: timers/core] time: tick-oneshot: Add missing Return and parameter " tip-bot2 for Sunday Adelodun

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®