Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Mon, 15 May 2017 09:40:44 -0700
Darren Hart <dvhart@infradead.org> escreveu:

> On Mon, May 15, 2017 at 01:49:19PM +0200, Peter Zijlstra wrote:
> > On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:  
> > > On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> wrote:  
> > > > The intention is to aid readability. Making comments worse so that some
> > > > retarded script can generate better html or whatnot is just that,
> > > > retarded.
> > > >
> > > > Code matters, generated documentation not so much. I'll take a comment
> > > > that reads well over one that generates pretty html any day.  
> > > 
> > > The deal is that if you start your comments with "/**" they'll be
> > > processed with the retarded script to produce pretty html.
> > > 
> > > For the most part the comments that generate pretty html also read well,
> > > and we don't expect or want anyone to go overboard with markup. I don't
> > > think it's unreasonable to make small concessions to improve generated
> > > documentation for people who care about it even if you don't.  
> > 
> > No. Such a concession has pure negative value. It opens the door to more
> > patches converting this or that comment to be prettier or whatnot. And
> > before you know it there's a Markus like idiot spamming you with dozens
> > of crap patches to prettify the generated crud.  
> 
> Well that I can certainly understand.
> 
> > 
> > Not to mention that this would mean having to learn this rest crud in
> > order to write these comments.  
> 
> I have complete confidence in you here Peter :-b
> 
> > 
> > All things I'm not prepared to do.
> > 
> > 
> > I'm all for useful comments, but I see no value _at_all_ in this
> > generated nonsense. The only reason I sometimes use the docbook comment
> > style is because its fairly uniform and the build bot gets you a warning
> > when your function signature no longer matches with the comment. But
> > if you make this painful I'll simply stop using them.
> >   
> 
> Making documentation more accessible to people is a good thing. This type of
> automated publication reduces the barrier to access. The lack of this kind of
> tooling, honestly, also discourages participation among some groups of
> of capable contributors.
> 
> That said, I support the direction both Mauro and Peter have voiced to minimize
> the impact to comment blocks. What does rest do with this formatting it doesn't
> understand - does it fail gracefully? Falling back to <verbatim> or something
> like that?

ReST produces a warning or error if it finds something it can't
parse, but it usually doesn't crash. The result of its output usually
is not what you would expect on such cases, though.

So, IMHO, the bare minimum to do is to make sure that it won't produce
errors/warnings.

PS.: kernel-doc itself also produce errors/warnings, if the vars at
the kernel-doc block don't match the ones at the function or if a
documented function was added or removed.

-

That's said, on the subsystems I maintain, I'm not satisfied with the
bare minimum ;) I usually build the html output and look into it
to be sure that the output from kernel-doc also looks nice.

In the case of the media subsystem, we have a big book describing the 
userspace API. Non-eventual media developers read the uAPI docs in html
or pdf for API docs before coding. 

So, on media subsysem, we ended by adding a few ReST specific
markups[1] where added, in order to improve its readability
in html/pdf, but the main documentation just use what's specified at
Documentation/doc-guide/kernel-doc.rst.

[1] There aren't much such markups used there. As far as I remember,
    we use:

    - bulleted lists like:
	    return:
	      - value 1
	      - value 2
	      ...

    - **bold** when we need to bold something;

    - ``literal`` for complex literal strings that %FOO won't handle
      (e. g. when it contains space and/or special chars);

    - ".. note::" or ".. attention::" in order to bold important
      notes, when some function have special requirements 
      to be called (for example, the need to lock or unlock 
      some mutex or spin lock before calling it).

      For example, the description for "v4l2_ctrl_handler_init_class"
      at:
	http://www.infradead.org/~mchehab/kernel_docs/media/kapi/v4l2-controls.html

      uses an attention markup that bolds that such function should
      not be called directly by API clients.

Thanks,
Mauro