[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <6c104724-1095-6307-1dbb-aefbb55dc5b1@infradead.org>
Date: Mon, 21 Nov 2022 16:09:43 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Steven Rostedt <rostedt@...dmis.org>,
Thomas Gleixner <tglx@...utronix.de>
Cc: LKML <linux-kernel@...r.kernel.org>,
Linus Torvalds <torvalds@...uxfoundation.org>,
Anna-Maria Behnsen <anna-maria@...utronix.de>,
Peter Zijlstra <peterz@...radead.org>,
Stephen Boyd <sboyd@...nel.org>,
Guenter Roeck <linux@...ck-us.net>,
Andrew Morton <akpm@...ux-foundation.org>,
Julia Lawall <Julia.Lawall@...ia.fr>,
Arnd Bergmann <arnd@...db.de>,
Viresh Kumar <viresh.kumar@...aro.org>,
Marc Zyngier <maz@...nel.org>,
Marcel Holtmann <marcel@...tmann.org>,
Johan Hedberg <johan.hedberg@...il.com>,
Luiz Augusto von Dentz <luiz.dentz@...il.com>,
linux-bluetooth@...r.kernel.org,
"David S. Miller" <davem@...emloft.net>,
Eric Dumazet <edumazet@...gle.com>,
Jakub Kicinski <kuba@...nel.org>,
Paolo Abeni <pabeni@...hat.com>, netdev@...r.kernel.org,
Jonathan Corbet <corbet@....net>
Subject: Re: [patch 06/15] timers: Update kernel-doc for various functions
On 11/21/22 12:43, Steven Rostedt wrote:
> On Tue, 15 Nov 2022 21:28:43 +0100 (CET)
> Thomas Gleixner <tglx@...utronix.de> wrote:
>
>> The kernel-doc of timer related functions is partially uncomprehensible
>> word salad. Rewrite it to make it useful.
>>
>> Signed-off-by: Thomas Gleixner <tglx@...utronix.de>
>> ---
>> kernel/time/timer.c | 131 ++++++++++++++++++++++++++++++----------------------
>> 1 file changed, 77 insertions(+), 54 deletions(-)
>>
>> --- a/kernel/time/timer.c
>> +++ b/kernel/time/timer.c
>> @@ -1121,14 +1121,16 @@ static inline int
>> }
>>
>> /**
>> - * mod_timer_pending - modify a pending timer's timeout
>> - * @timer: the pending timer to be modified
>> - * @expires: new timeout in jiffies
>> + * mod_timer_pending - Modify a pending timer's timeout
>> + * @timer: The pending timer to be modified
>> + * @expires: New timeout in jiffies
>> *
>> - * mod_timer_pending() is the same for pending timers as mod_timer(),
>> - * but will not re-activate and modify already deleted timers.
>> + * mod_timer_pending() is the same for pending timers as mod_timer(), but
>> + * will not activate inactive timers.
>> *
>> - * It is useful for unserialized use of timers.
>> + * Return:
>> + * * %0 - The timer was inactive and not modified
>> + * * %1 - The timer was active and requeued to expire at @expires
>
> I didn't know of the '%' option in kernel-doc.
>
> Looking it up, I see it's for constants. Although it's missing in the
> examples for return values:
>
> Documentation/doc-guide/kernel-doc.rst:
>
> ```
> Return values
> ~~~~~~~~~~~~~
>
> The return value, if any, should be described in a dedicated section
> named ``Return``.
>
> .. note::
>
> #) The multi-line descriptive text you provide does *not* recognize
> line breaks, so if you try to format some text nicely, as in::
>
> * Return:
> * 0 - OK
> * -EINVAL - invalid argument
> * -ENOMEM - out of memory
>
> this will all run together and produce::
>
> Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
>
> So, in order to produce the desired line breaks, you need to use a
> ReST list, e. g.::
>
> * Return:
> * * 0 - OK to runtime suspend the device
> * * -EBUSY - Device should not be runtime suspended
> ```
>
> Should this be updated?
Sure. Do you want to do it?
--
~Randy
Powered by blists - more mailing lists