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

["Rafael J. Wysocki" <rjw@rjwysocki.net>]

On Sunday, June 25, 2017 05:32:31 PM Matthew Wilcox wrote:
> 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

There also is information on various frameworks that driver writers are expected
to use and honestly various mixtures of that with 1. above.

Mutual exclusion mechanisms also need to be documented properly IMO and so on.

> 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.
> 
> On 24 Jun 2017 9:41 am, "Mauro Carvalho Chehab" <mchehab@s-opensource.com>
> wrote:
> 
> Yeah, one of the problems with existing documentation is that,
> sometimes, the same document describes both userspace-relevant
> info and kernelspace APIs.

Right.

But, alas, those things happen to be related, especially when framework-provided
sysfs attributes and similar come into play.  With the current layout of things
it sometimes is hard to avoid documenting the same thing in two different
places, risking that the two descriptions of the same thing will diverge in the
future eventually.

Moreover, does debugfs fall into "user documentation" or "developer documentation",
for example?

And generally documentation on how to diagnose problems for that matter?