Re: [tip:timers/core] hrtimer: Use a bullet for the returns bullet list

[Joe Perches <joe@perches.com>]

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.

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.

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.

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