August 3, 2015
Related Material:
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
(checkpatch.pl?),
and even if tools can automatically generate this documentation.
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.
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.
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 https://www.kernel.org/doc/htmldocs/), 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.
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 git.kernel.org.