Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 18:52:20 +0200
Andrea Parri <andrea.parri@xxxxxxxxxxxxxxxxxxxx> escreveu:

> On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote:
> > On Thu, 10 May 2018 14:23:35 +0200
> > Andrea Parri <andrea.parri@xxxxxxxxxxxxxxxxxxxx> wrote:
> >   
> > > only
> > > remember that other people (including some developers running into the
> > > "disadventure" of opening an RST doc. from their preferred text editor
> > > and being brought to conclude:  "WTH!  I need to open a web browser, I
> > > guess...") _use_ such doc. and _do care_ about it, and that what might
> > > be an improvement for some people might look as "vandalizing" to others.  
> > 
> > If you have an example of a place where use of a web browser has been
> > made mandatory, please point it out.  Avoiding that was at the top of the
> > list of explicit requirements.  
> 
> That's all I need.
> 
> 
> >Surely an extra colon is not going to
> > force you to run screaming to the protective embrace of Firefox...?  
> 
> Let me put it in these terms: I believe that that extra colon (or the
> "diagram" keywork) is not going to improve/help my use of the doc. ;D

No, it won't improve, but, it won't make it harder for a human
to understand if a "diagram" or "::" is added at the description.

The thing is that we need something that works for the Kernel as
a hole, and not just on a few places.

On some subsystems, just a text is not good enough to describe
things. See, for example:
	https://www.kernel.org/doc/html/latest/media/uapi/v4l/crop.html
	https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-packed-rgb.html
	https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-srggb10-ipu3.html
	https://www.kernel.org/doc/html/latest/gpu/drm-kms.html

Images, complex tables, etc are sometimes required to show some things.
Trying to explain just on text is harder to write, longer and worse
for readers. In the past, DocBook was used. ReST made very simple to
write documentation. From where I sit, I'm reviewing documentation
patches from a lot more people than the usage of a markup language.

As a bonus, we can now create cross-references for kernel-doc functions,
with is really great when reading documentation for complex hardware.

From where I sit at media, the subsystem documentation, if generated
in PDF, becomes a book with more than 1,100 pages, full of long tables,
images and graphs[1], covering uAPI, kAPI and driver-specific
documentation.

[1] https://linuxtv.org/downloads/v4l-dvb-apis-new/media.pdf

As on all subsystems, developers write documentation directly
at .rst or as kernel-doc comments. But for reading it, even developers
prefer to read the docs via the html (or pdf) output, as it better
shows tables and images. It is also faster to follow the dozen
thousands of links inside it.

The point is: we shouldn't enforce everyone to use our own view
about how to navigate through documentation. People are free to
use whatever improves their workflow.

Thanks,
Mauro