Re: [tip:timers/core] hrtimer: Use a bullet for the returns bullet list
From: Mauro Carvalho Chehab
Date: Thu Jun 27 2019 - 20:39:41 EST
Em Thu, 27 Jun 2019 15:08:59 -0700
Joe Perches <joe@xxxxxxxxxxx> escreveu:
> On Thu, 2019-06-27 at 14:46 -0700, tip-bot for Mauro Carvalho Chehab
> > Commit-ID: 516337048fa40496ae5ca9863c367ec991a44d9a
> > Gitweb: https://git.kernel.org/tip/516337048fa40496ae5ca9863c367ec991a44d9a
> > Author: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>
> > AuthorDate: Mon, 24 Jun 2019 07:33:26 -0300
> > Committer: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
> > CommitDate: Thu, 27 Jun 2019 23:30:04 +0200
> > hrtimer: Use a bullet for the returns bullet list
> > That gets rid of this warning:
> > ./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.
> Doesn't this form occur multiple dozens of times in
> kernel sources?
> For instance:
> $ git grep -B3 -A5 -P "^ \* Returns:?$" | \
> grep -P -A8 '\-\s+\*\s*@\w+:'
Yes, this is a common pattern, but not all patterns that match the above
regex are broken.
> I think the warning is odd at best and docutils might
> be updated or the warning ignored or suppressed.
> > and displays nicely both at the source code and at the produced
> > documentation.
The warnings are painful - and they're the main reason why I wrote this
change: - I wanted to avoid new warnings actually unrelated to my
changes that were sometimes appearing while doing incremental
"make htmldocs" on a big patchset that I've been rebasing almost every
week over the last two months.
Yet, did you try to look how this pattern will appear at the html and pdf
output? Something like this:
sound/soc/codecs/wm8960.c: * Returns:
sound/soc/codecs/wm8960.c- * -1, in case no sysclk frequency available found
sound/soc/codecs/wm8960.c- * >=0, in case we could derive bclk and lrclk from sysclk using
sound/soc/codecs/wm8960.c- * (@sysclk_idx, @dac_idx, @bclk_idx) dividers
Will be displayed as:
-1, in case no sysclk frequency available found **>=0, in case we could derive bclk and lrclk from sysclk using** (@sysclk_idx, @dac_idx, @bclk_idx) dividers
(where **foo**) means that "foo" will be printed in bold.
E. g. it will just merge all returns values into a single line and, if
there are alignment differences, it will make the previous line bold
and produce a warning.
On some places, however, what's there will be properly displayed,
like this one:
* wimax_reset - Reset a WiMAX device
* @wimax_dev: WiMAX device descriptor
* %0 if ok and a warm reset was done (the device still exists in
* the system).
* -%ENODEV if a cold/bus reset had to be done (device has
* disconnected and reconnected, so current handle is not valid
* any more).
* -%EINVAL if the device is not even registered.
* Any other negative error code shall be considered as
As there are blank lines between each value, making each return code a
tools/lib/traceevent/parse-filter.c: * Returns:
tools/lib/traceevent/parse-filter.c- * 1 if the two filters hold the same content.
tools/lib/traceevent/parse-filter.c- * 0 if they do not.
will also not mangle too much, as the dots will help for someone to
understand, if reading the html/pdf output, like this:
1 if the two filters hold the same content. 0 if they do not.
So, it all depends on the context.
While it would likely be possible to improve kernel-doc to present better
results, I'm afraid that it would be too complex for simple regex
expressions, and hard to tune, as it would be a hint-based approach,
and doing a natural language processing would be too much effort.
> > diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
> > @@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
> > * @timer: hrtimer to stop
> > *
> > * Returns:
> > - * 0 when the timer was not active
> > - * 1 when the timer was active
> > - * -1 when the timer is currently executing the callback function and
> > + *
> > + * * 0 when the timer was not active
> > + * * 1 when the timer was active
> > + * * -1 when the timer is currently executing the callback function and
> > * cannot be stopped
> > */
> > int hrtimer_try_to_cancel(struct hrtimer *timer)