Em Thu, 27 Jun 2019 19:40:24 -0700 Joe Perches <joe@xxxxxxxxxxx> 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@xxxxxxxxxxx> 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
