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:   Fri, 28 Jun 2019 10:10:47 -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: <20190628101047.36927826@coco.lan>
In-Reply-To: <2f1c88882fde00beebb6066e9bd561287f5932c5.camel@perches.com>
References: <74ddad7dac331b4e5ce4a90e15c8a49e3a16d2ac.1561372382.git.mchehab+samsung@kernel.org>
        <tip-516337048fa40496ae5ca9863c367ec991a44d9a@git.kernel.org>
        <3740b16e5d0a3144e2d48af7cf56ae8020c3f9af.camel@perches.com>
        <20190627213930.0d28a072@coco.lan>
        <2f1c88882fde00beebb6066e9bd561287f5932c5.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 19:40:24 -0700
Joe Perches <joe@perches.com> escreveu:

> On Thu, 2019-06-27 at 21:39 -0300, Mauro Carvalho Chehab wrote:
> > Em Thu, 27 Jun 2019 15:08:59 -0700
> > Joe Perches <joe@perches.com> escreveu:  
> []
> > > > 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?  
> 
> No I did not.
> 
> I just would like to avoid changing perfectly intelligible
> kernel-doc content into something less directly readable for
> the sake of external output.
> 
> I don't use the externally generated formatted output docs.
> I read and use the source when necessary.

Yeah, I do the same too, except when I want to se the hole
picture or on complex subsystems. You can't really understand
media subsystems if you don't read it from the docs, as
the rationale for a lot of things are there.

Yet, for newcomers that are studying a new subsystem, a
good documentation helps a lot.

> 
> Automatic creation of bulleted blocks from relatively
> unformatted content is a hard problem.
> 
> I appreciate the work Mauro, I just would like to minimize
> the necessary changes if possible.

Yeah, me too.

> 
> The grep I did was trivial, I'm sure there are better tools
> to isolate the kernel-doc bits where the Return: block
> is emitted.
> 
> 
> >  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.>   
> 
> That's a yuck from me.

Agreed, but, when writing text docs, doing something like:

	parameter
		parameter description

and getting the first line bolded helps to reduce the need of
adding explicit bold markups and produce a nice visual.

> 
> > 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.  
> 
> Yeah, tough problem.  I don't envy it.
> 
> cheers and g'luck...

Thank you!

Thanks,
Mauro