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;
Message-ID: <3740b16e5d0a3144e2d48af7cf56ae8020c3f9af.camel@perches.com>
Subject: Re: [tip:timers/core] hrtimer: Use a bullet for the returns bullet
 list
From:   Joe Perches <joe@perches.com>
To:     corbet@lwn.net, linux-doc@vger.kernel.org, tglx@linutronix.de,
        mingo@kernel.org, mchehab@infradead.org, hpa@zytor.com,
        linux-kernel@vger.kernel.org, mchehab+samsung@kernel.org,
        linux-tip-commits@vger.kernel.org
Cc:     docutils-develop@lists.sourceforge.net
Date:   Thu, 27 Jun 2019 15:08:59 -0700
In-Reply-To: <tip-516337048fa40496ae5ca9863c367ec991a44d9a@git.kernel.org>
References: <74ddad7dac331b4e5ce4a90e15c8a49e3a16d2ac.1561372382.git.mchehab+samsung@kernel.org>
         <tip-516337048fa40496ae5ca9863c367ec991a44d9a@git.kernel.org>
Content-Type: text/plain; charset="ISO-8859-1"
User-Agent: Evolution 3.30.5-0ubuntu0.18.10.1 
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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+:'

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.

> 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)