Peter Huewe: Documentation

August 3, 2015

Related Material:

  1. Documentation/kernel-doc-nano-HOWTO.txt

Additional Participants: Alexey Dobriyan, Daniel Vetter, Davidlohr Bueso, David Woodhouse, Dmitry Torokhov, Jason Cooper, Johannes Berg, Jonathan Corbet, Julia Lawall, Konstantin Ryabitsev, Lai Jiangshan, Laurent Pinchart, Mauro Carvalho Chehab, Rafael J. Wysocki, Randy Dunlap, Steven Rostedt, and Zefan Li.

People tagged: @@@

Please note that this is a summarized summary.

Peter Huewe reviewed Documentation/kernel-doc-nano-HOWTO.txt and noted that, counter to its strictures, we don't tend to consistently docbook-document functions exported by EXPORT_SYMBOL, functions externally visible to other files, and, optionally, for functions marked static. Peter asks if tools can spot missing documentation (, and even if tools can automatically generate this documentation.


Julia Lawall pointed out that Coccinelle cannot help find missing docbook comments due to the fact that it ignores all comments, but suggests that a simple script based on grep might do the trick. Mauro Carvalho suggested also classifying the symbols based on how heavily and widely used they are. Mauro also suggests that LXR might help with such classification.

Just Say No to kernel-doc!!!

Alexey Dobriyan took the contrarian position, arguing that newbies should not write documentation because they by definition do not know much about the code. Alexey therefore instead suggests deprecating kernel-doc, removing the scripts, and shrinking voluminous header comments, giving module_refcount() as an example in great need of shrinkage. Randy Dunlap agreed, noting that the kernel-doc scripts are fragile. However, Randy strongly believes that new interfaces need good documentation somewhere, though not necessarily via kernel-doc. Steven Rostedt agreed that newbies should not write documentation, but pointed out that newbies can be a good source of good questions leading to good documentation, adding that he himself sometimes wonders what an unfamiliar Linux-kernel function is supposed to do. However, Steven also said that by “newbies”, he means experienced kernel developers new to a particular subsystem.

David Woodhouse objected that if a given function is so complex that Steven needs an explanation, then that function should have been made simpler or there should be a comment giving an explanation. Steven agreed, and suggested that old uncommented functions should be documented. Steven also suggested that the comments do not match the code, they probably are both wrong. Peter Huewe feels that fast-paced development may leave documentation behind, and that as people locate difficult-to-understand code, they should add documentation.

Jason Cooper gave a counter-example (though perhaps one that proves the rule?) in the guise of Stephan Mueller, who wrote highly regarded documentation for the Crypto API within a year of submitting his first patch. Peter Huewe agreed that newbies are good at finding blind spots, and someone pointed out the DRM framework's docbook as another example of this.

Just Say Yes to kernel-doc!!!

Jon Corbet believes that kernel docbook does work well enough for people to use it, so that it should not be removed until it has been replaced by something better (though he agrees that docbook is a major pain). Peter Huewe asked for the generated files, as he cannot get it to work out of the box (Johannes Berg pointed to, and suggests doxygen as a candidate “something better”. Jon Corbet agreed that doxygen might be worth a look, but also called out Sphinx, Markdown, or ReST as also worth a look. Daniel Vetter described some docbook efforts after being summoned by Laurent Pinchart. Mauro Carvalho Chehab also called for doxygen, noting that some drivers are submitted with doxygen-compatible tags, and that converting to docbook is usually not worth the effort (and requesting it of the submitter usually results in comments being stripped instead).

Jon Corbet pointed out that any change that required rewriting all existing header comments is likely a non-starter, and Laurent Pinchart pointed out that any documentation in any format is better than no documentation at all.

What, How, and Who?

Lai Jiangshan called for documentation at the architecture and design level in addition to the code level. Jon Corbet asked that people refer any people willing and able to write coherently about kernel internals.

Jon favors discussing the alternatives at Kernel Summit. Davidlohr Bueso suggested improving the Documentation/ directory contents, calling out the merits of nicely formatted plain-text files over automated systems, to which Rafael J. Wysocki agreed. Jon emphatically agreed that writing of documenting APIs cannot reasonably be automated, but argued that the effort invested into the existing hand-written docbook comments should be perserved. Dmitry Torokhov would like docbook to be generated by default and to generate more quickly.

Konstantin Ryabitsev offered to turn on the “render markdown” plugin on