* [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
* 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
* [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
* [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®