Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Thu, 27 Jun 2019 21:39:30 -0300
From:   Mauro Carvalho Chehab <mchehab@infradead.org>
To:     Joe Perches <joe@perches.com>
Cc:     corbet@lwn.net, linux-doc@vger.kernel.org, tglx@linutronix.de,
        mingo@kernel.org, hpa@zytor.com, linux-kernel@vger.kernel.org,
        mchehab+samsung@kernel.org, linux-tip-commits@vger.kernel.org,
        docutils-develop@lists.sourceforge.net
Subject: Re: [tip:timers/core] hrtimer: Use a bullet for the returns bullet
 list
Message-ID: <20190627213930.0d28a072@coco.lan>
In-Reply-To: <3740b16e5d0a3144e2d48af7cf56ae8020c3f9af.camel@perches.com>
References: <74ddad7dac331b4e5ce4a90e15c8a49e3a16d2ac.1561372382.git.mchehab+samsung@kernel.org>
        <tip-516337048fa40496ae5ca9863c367ec991a44d9a@git.kernel.org>
        <3740b16e5d0a3144e2d48af7cf56ae8020c3f9af.camel@perches.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Em Thu, 27 Jun 2019 15:08:59 -0700
Joe Perches <joe@perches.com> escreveu:

> On Thu, 2019-06-27 at 14:46 -0700, tip-bot for Mauro Carvalho Chehab
> wrote:
> > Commit-ID:  516337048fa40496ae5ca9863c367ec991a44d9a
> > Gitweb:     https://git.kernel.org/tip/516337048fa40496ae5ca9863c367ec991a44d9a
> > Author:     Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > AuthorDate: Mon, 24 Jun 2019 07:33:26 -0300
> > Committer:  Thomas Gleixner <tglx@linutronix.de>
> > 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:

	**Returns:**
	  -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
 *
 * Returns:
 *
 * %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
 * non-recoverable.
 *

As there are blank lines between each value, making each return code a
different line.

This one:

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:

	**Returns:**
	  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)  
> 


Thanks,
Mauro