Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues

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

Em Sun, 25 Jun 2017 17:32:31 -0400
Matthew Wilcox <willy6545@gmail.com> escreveu:

> I find documentation comes in the following bins:
> 
> 1. User documentation (possible sub-split into "how to use this from kernel
> space" and "how to use this from user space")
> 2. Information for someone who's interested in modifying the code. Possibly
> including architectural considerations (eg locking), performance, ideas for
> future improvement, etc.
> 3. Random swearing and abuse
> 
> I think the second and third categories of documentation should be kept out
> of the kernel books and left as plain comments by the code.

Having comments together the code is good, but sometimes it is not enough.

Just as an example, last week I received two patch series, from
different developers, that didn't get right how to collect quality
measurements from digital TV frontends. The functions they use are
documented via kernel-doc, and they looked on other drivers as examples.
Still, that was not not clear enough, as both developers didn't quite
get some things.

So, I had to write a few patches to actually explain how a
frontend driver is expected to collect statistics:
	https://patchwork.linuxtv.org/patch/42081/

And, today, I complemented with two additional texts:

	https://patchwork.linuxtv.org/patch/42115/
	https://patchwork.linuxtv.org/patch/42116/

As those explanations complement the kernel-doc macros from
dvb_frontend.h, they need cross references, in order for the
driver developer to better understand how things are connected,
and to avoid the need of having to explain everything that it is
already documented via kernel-doc tags, as can be seeing at:

	https://www.infradead.org/~mchehab/kernel_docs/media/kapi/dtv-core.html#digital-tv-frontend-kabi


That's just today's example. There are plenty of cases where we
need to add images and complex tables, etc that just don't fit
well as plain text.

Thanks,
Mauro