When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(kernel/timer.c:230): No description found for return value of
'round_jiffies'
Fix them by:
- Using "Return:" sections to introduce the descriptions of return values.
- Adding missing descriptions.
Signed-off-by: Yacine Belkadi <yacine.belkadi.1@xxxxxxxxx>
---
Applied to d2b4a646717153a1a180b64d4a8464054dbd700e
kernel/hrtimer.c | 27 +++++++++++++++++----------
kernel/timer.c | 40 ++++++++++++++++++++++++++++++----------
2 files changed, 47 insertions(+), 20 deletions(-)
diff --git a/kernel/hrtimer.c b/kernel/hrtimer.c
index f0f4fe2..89696c9 100644
--- a/kernel/hrtimer.c
+++ b/kernel/hrtimer.c
@@ -277,7 +277,7 @@ lock_hrtimer_base(const struct hrtimer *timer, unsigned long *flags)
* @kt: addend
* @nsec: the scalar nsec value to add
*
- * Returns the sum of kt and nsec in ktime_t format
+ * Return: The sum of @kt and @nsec in ktime_t format.
*/
ktime_t ktime_add_ns(const ktime_t kt, u64 nsec)
{
@@ -305,7 +305,7 @@ EXPORT_SYMBOL_GPL(ktime_add_ns);
* @kt: minuend
* @nsec: the scalar nsec value to subtract
*
- * Returns the subtraction of @nsec from @kt in ktime_t format
+ * Return: The subtraction of @nsec from @kt in ktime_t format.
*/
ktime_t ktime_sub_ns(const ktime_t kt, u64 nsec)
{
@@ -836,7 +836,8 @@ void unlock_hrtimer_base(const struct hrtimer *timer, unsigned long *flags)
* @interval: the interval to forward
*
* Forward the timer expiry so it will expire in the future.
- * Returns the number of overruns.
+ *
+ * Return: The number of overruns.
*/
u64 hrtimer_forward(struct hrtimer *timer, ktime_t now, ktime_t interval)
{
@@ -1038,7 +1039,7 @@ int __hrtimer_start_range_ns(struct hrtimer *timer, ktime_t tim,
* @mode: expiry mode: absolute (HRTIMER_MODE_ABS) or
* relative (HRTIMER_MODE_REL)
*
- * Returns:
+ * Return:
* 0 on success
* 1 when the timer was active
*/
@@ -1056,7 +1057,7 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
* @mode: expiry mode: absolute (HRTIMER_MODE_ABS) or
* relative (HRTIMER_MODE_REL)
*
- * Returns:
+ * Return:
* 0 on success
* 1 when the timer was active
*/
@@ -1072,7 +1073,7 @@ EXPORT_SYMBOL_GPL(hrtimer_start);
* hrtimer_try_to_cancel - try to deactivate a timer
* @timer: hrtimer to stop
*
- * Returns:
+ * Return:
* 0 when the timer was not active
* 1 when the timer was active
* -1 when the timer is currently excuting the callback function and
@@ -1100,7 +1101,7 @@ EXPORT_SYMBOL_GPL(hrtimer_try_to_cancel);
* hrtimer_cancel - cancel a timer and wait for the handler to finish.
* @timer: the timer to be cancelled
*
- * Returns:
+ * Return:
* 0 when the timer was not active
* 1 when the timer was active
*/
@@ -1119,6 +1120,8 @@ EXPORT_SYMBOL_GPL(hrtimer_cancel);
/**
* hrtimer_get_remaining - get remaining time for the timer
* @timer: the timer to read
+ *
+ * Return: The remaining time for @timer.
*/
ktime_t hrtimer_get_remaining(const struct hrtimer *timer)
{
@@ -1137,7 +1140,7 @@ EXPORT_SYMBOL_GPL(hrtimer_get_remaining);
/**
* hrtimer_get_next_event - get the time until next expiry event
*
- * Returns the delta to the next expiry event or KTIME_MAX if no timer
+ * Return: The delta to the next expiry event or KTIME_MAX if no timer
* is pending.
*/
ktime_t hrtimer_get_next_event(void)
@@ -1220,6 +1223,8 @@ EXPORT_SYMBOL_GPL(hrtimer_init);
*
* Store the resolution of the clock selected by @which_clock in the
* variable pointed to by @tp.
+ *
+ * Return: 0
*/
int hrtimer_get_res(const clockid_t which_clock, struct timespec *tp)
{
@@ -1793,6 +1798,8 @@ void __init hrtimers_init(void)
* @delta: slack in expires timeout (ktime_t)
* @mode: timer mode, HRTIMER_MODE_ABS or HRTIMER_MODE_REL
* @clock: timer clock, CLOCK_MONOTONIC or CLOCK_REALTIME
+ *
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched
schedule_hrtimeout_range_clock(ktime_t *expires, unsigned long delta,
@@ -1864,7 +1871,7 @@ schedule_hrtimeout_range_clock(ktime_t *expires, unsigned long delta,
* The current task state is guaranteed to be TASK_RUNNING when this
* routine returns.
*
- * Returns 0 when the timer has expired otherwise -EINTR
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched schedule_hrtimeout_range(ktime_t *expires, unsigned long delta,
const enum hrtimer_mode mode)
@@ -1894,7 +1901,7 @@ EXPORT_SYMBOL_GPL(schedule_hrtimeout_range);
* The current task state is guaranteed to be TASK_RUNNING when this
* routine returns.
*
- * Returns 0 when the timer has expired otherwise -EINTR
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched schedule_hrtimeout(ktime_t *expires,
const enum hrtimer_mode mode)
diff --git a/kernel/timer.c b/kernel/timer.c
index 15bc1b4..3fe6ab0 100644
--- a/kernel/timer.c
+++ b/kernel/timer.c
@@ -174,7 +174,7 @@ static unsigned long round_jiffies_common(unsigned long j, int cpu,
* processors firing at the exact same time, which could lead
* to lock contention or spurious cache line bouncing.
*
- * The return value is the rounded version of the @j parameter.
+ * Return: The rounded version of the @j parameter.
*/
unsigned long __round_jiffies(unsigned long j, int cpu)
{
@@ -200,7 +200,7 @@ EXPORT_SYMBOL_GPL(__round_jiffies);
* processors firing at the exact same time, which could lead
* to lock contention or spurious cache line bouncing.
*
- * The return value is the rounded version of the @j parameter.
+ * Return: The rounded version of the @j parameter.
*/
unsigned long __round_jiffies_relative(unsigned long j, int cpu)
{
@@ -224,7 +224,7 @@ EXPORT_SYMBOL_GPL(__round_jiffies_relative);
* at the same time, rather than at various times spread out. The goal
* of this is to have the CPU wake up less, which saves power.
*
- * The return value is the rounded version of the @j parameter.
+ * Return: The rounded version of the @j parameter.
*/
unsigned long round_jiffies(unsigned long j)
{
@@ -245,7 +245,7 @@ EXPORT_SYMBOL_GPL(round_jiffies);
* at the same time, rather than at various times spread out. The goal
* of this is to have the CPU wake up less, which saves power.
*
- * The return value is the rounded version of the @j parameter.
+ * Return: The rounded version of the @j parameter.
*/
unsigned long round_jiffies_relative(unsigned long j)
{
@@ -262,6 +262,8 @@ EXPORT_SYMBOL_GPL(round_jiffies_relative);
* round down. This is useful for timeouts for which the exact time
* of firing does not matter too much, as long as they don't fire too
* early.
+ *
+ * Return: The rounded version of the @j parameter.
*/
unsigned long __round_jiffies_up(unsigned long j, int cpu)
{
@@ -278,6 +280,8 @@ EXPORT_SYMBOL_GPL(__round_jiffies_up);
* round down. This is useful for timeouts for which the exact time
* of firing does not matter too much, as long as they don't fire too
* early.
+ *
+ * Return: The rounded version of the @j parameter.
*/
unsigned long __round_jiffies_up_relative(unsigned long j, int cpu)
{
@@ -296,6 +300,8 @@ EXPORT_SYMBOL_GPL(__round_jiffies_up_relative);
* round down. This is useful for timeouts for which the exact time
* of firing does not matter too much, as long as they don't fire too
* early.
+ *
+ * Return: The rounded version of the @j parameter.
*/
unsigned long round_jiffies_up(unsigned long j)
{
@@ -311,6 +317,8 @@ EXPORT_SYMBOL_GPL(round_jiffies_up);
* round down. This is useful for timeouts for which the exact time
* of firing does not matter too much, as long as they don't fire too
* early.
+ *
+ * Return: The rounded version of the @j parameter.
*/
unsigned long round_jiffies_up_relative(unsigned long j)
{
@@ -783,6 +791,8 @@ out_unlock:
* but will not re-activate and modify already deleted timers.
*
* It is useful for unserialized use of timers.
+ *
+ * Return: 1 if the timer was modified. 0 otherwise.
*/
int mod_timer_pending(struct timer_list *timer, unsigned long expires)
{
@@ -845,8 +855,8 @@ unsigned long apply_slack(struct timer_list *timer, unsigned long expires)
* same timer, then mod_timer() is the only safe way to modify the timeout,
* since add_timer() cannot modify an already running timer.
*
- * The function returns whether it has modified a pending timer or not.
- * (ie. mod_timer() of an inactive timer returns 0, mod_timer() of an
+ * Return: The function returns whether it has modified a pending timer or
+ * not. (ie. mod_timer() of an inactive timer returns 0, mod_timer() of an
* active timer returns 1.)
*/
int mod_timer(struct timer_list *timer, unsigned long expires)
@@ -874,6 +884,8 @@ EXPORT_SYMBOL(mod_timer);
* active timer (if the timer is inactive it will be activated)
* and to ensure that the timer is scheduled on the current CPU.
*
+ * Return: 1 if the timer was modified. 0 otherwise.
+ *
* Note that this does not prevent the timer from being migrated
* when the current CPU goes offline. If this is a problem for
* you, use CPU-hotplug notifiers to handle it correctly, for
@@ -952,9 +964,9 @@ EXPORT_SYMBOL_GPL(add_timer_on);
* del_timer() deactivates a timer - this works on both active and inactive
* timers.
*
- * The function returns whether it has deactivated a pending timer or not.
- * (ie. del_timer() of an inactive timer returns 0, del_timer() of an
- * active timer returns 1.)
+ * Return: The function returns whether it has deactivated a pending timer
+ * or not. (ie. del_timer() of an inactive timer returns 0, del_timer() of
+ * an active timer returns 1.)
*/
int del_timer(struct timer_list *timer)
{
@@ -981,6 +993,8 @@ EXPORT_SYMBOL(del_timer);
*
* This function tries to deactivate a timer. Upon successful (ret >= 0)
* exit the timer is not queued and the handler is not running on any CPU.
+ *
+ * Return: >= 0 on success.
*/
int try_to_del_timer_sync(struct timer_list *timer)
{
@@ -1037,7 +1051,8 @@ EXPORT_SYMBOL(try_to_del_timer_sync);
* The interrupt on the other CPU is waiting to grab somelock but
* it has interrupted the softirq that CPU0 is waiting to finish.
*
- * The function returns whether it has deactivated a pending timer or not.
+ * Return: The function returns whether it has deactivated a pending timer
+ * or not.
*/
int del_timer_sync(struct timer_list *timer)
{
@@ -1314,6 +1329,8 @@ static unsigned long cmp_next_hrtimer_event(unsigned long now,
/**
* get_next_timer_interrupt - return the jiffy of the next pending timer
* @now: current time (in jiffies)
+ *
+ * Return: The jiffy of the next pending timer.
*/
unsigned long get_next_timer_interrupt(unsigned long now)
{
@@ -1673,6 +1690,9 @@ EXPORT_SYMBOL(msleep);
/**
* msleep_interruptible - sleep waiting for signals
* @msecs: Time in milliseconds to sleep for
+ *
+ * Return: 0 if the sleep was not interrupted by a signal. Otherwise,
+ * the remaining time in jiffies.
*/
unsigned long msleep_interruptible(unsigned int msecs)
{
--
1.7.10.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
