[Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues

[Mauro Carvalho Chehab]

Em Sun, 25 Jun 2017 23:42:20 +0200
"Rafael J. Wysocki" <rjw at rjwysocki.net> escreveu:

> 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 at 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.
> 

Well, sysfs attribute description is currently a little messy, IMHO.
We have (or should have) all of them described under Documentation/ABI/,
but it is not uncommon to have them described on some other random
places. As things get bitrot, we end by having different descriptions
on each place.

I also suspect that some sysfs descriptions are only outside
Documentation/ABI/ (although I never actually tried to seek for such
issue).

> Moreover, does debugfs fall into "user documentation" or "developer documentation",
> for example?
> 
> And generally documentation on how to diagnose problems for that matter?

The same thing for sysfs applies to debugfs.

IMHO, debugfs and information about how to diagnose problems
belong to "user documentation" / "how to use this from user space"
(using Matthew's classification), in the sense that an advanced
admin may use them, in order to properly address some issue that
will eventually generate a bug report (either for Kernel or to some
application/library).

Thanks,
Mauro