1.. SPDX-License-Identifier: GPL-2.0 2How to help improve kernel documentation 3======================================== 4 5Documentation is an important part of any software-development project. 6Good documentation helps to bring new developers in and helps established 7developers work more effectively. Without top-quality documentation, a lot 8of time is wasted in reverse-engineering the code and making avoidable 9mistakes. 10 11Unfortunately, the kernel's documentation currently falls far short of what 12it needs to be to support a project of this size and importance. 13 14This guide is for contributors who would like to improve that situation. 15Kernel documentation improvements can be made by developers at a variety of 16skill levels; they are a relatively easy way to learn the kernel process in 17general and find a place in the community. The bulk of what follows is the 18documentation maintainer's list of tasks that most urgently need to be 19done. 20 21The documentation TODO list 22--------------------------- 23 24There is an endless list of tasks that need to be carried out to get our 25documentation to where it should be. This list contains a number of 26important items, but is far from exhaustive; if you see a different way to 27improve the documentation, please do not hold back! 28 29Addressing warnings 30~~~~~~~~~~~~~~~~~~~ 31 32The documentation build currently spews out an unbelievable number of 33warnings. When you have that many, you might as well have none at all; 34people ignore them, and they will never notice when their work adds new 35ones. For this reason, eliminating warnings is one of the highest-priority 36tasks on the documentation TODO list. The task itself is reasonably 37straightforward, but it must be approached in the right way to be 38successful. 39 40Warnings issued by a compiler for C code can often be dismissed as false 41positives, leading to patches aimed at simply shutting the compiler up. 42Warnings from the documentation build almost always point at a real 43problem; making those warnings go away requires understanding the problem 44and fixing it at its source. For this reason, patches fixing documentation 45warnings should probably not say "fix a warning" in the changelog title; 46they should indicate the real problem that has been fixed. 47 48Another important point is that documentation warnings are often created by 49problems in kerneldoc comments in C code. While the documentation 50maintainer appreciates being copied on fixes for these warnings, the 51documentation tree is often not the right one to actually carry those 52fixes; they should go to the maintainer of the subsystem in question. 53 54For example, in a documentation build I grabbed a pair of warnings nearly 55at random:: 56 57 ./drivers/devfreq/devfreq.c:1818: warning: bad line: 58 - Resource-managed devfreq_register_notifier() 59 ./drivers/devfreq/devfreq.c:1854: warning: bad line: 60 - Resource-managed devfreq_unregister_notifier() 61 62(The lines were split for readability). 63 64A quick look at the source file named above turned up a couple of kerneldoc 65comments that look like this:: 66 67 /** 68 * devm_devfreq_register_notifier() 69 - Resource-managed devfreq_register_notifier() 70 * @dev: The devfreq user device. (parent of devfreq) 71 * @devfreq: The devfreq object. 72 * @nb: The notifier block to be unregistered. 73 * @list: DEVFREQ_TRANSITION_NOTIFIER. 74 */ 75 76The problem is the missing "*", which confuses the build system's 77simplistic idea of what C comment blocks look like. This problem had been 78present since that comment was added in 2016 — a full four years. Fixing 79it was a matter of adding the missing asterisks. A quick look at the 80history for that file showed what the normal format for subject lines is, 81and ``scripts/get_maintainer.pl`` told me who should receive it. The 82resulting patch looked like this:: 83 84 [PATCH] PM / devfreq: Fix two malformed kerneldoc comments 85 86 Two kerneldoc comments in devfreq.c fail to adhere to the required format, 87 resulting in these doc-build warnings: 88 89 ./drivers/devfreq/devfreq.c:1818: warning: bad line: 90 - Resource-managed devfreq_register_notifier() 91 ./drivers/devfreq/devfreq.c:1854: warning: bad line: 92 - Resource-managed devfreq_unregister_notifier() 93 94 Add a couple of missing asterisks and make kerneldoc a little happier. 95 96 Signed-off-by: Jonathan Corbet <corbet@lwn.net> 97 --- 98 drivers/devfreq/devfreq.c | 4 ++-- 99 1 file changed, 2 insertions(+), 2 deletions(-) 100 101 diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c 102 index 57f6944d65a6..00c9b80b3d33 100644 103 --- a/drivers/devfreq/devfreq.c 104 +++ b/drivers/devfreq/devfreq.c 105 @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res) 106 107 /** 108 * devm_devfreq_register_notifier() 109 - - Resource-managed devfreq_register_notifier() 110 + * - Resource-managed devfreq_register_notifier() 111 * @dev: The devfreq user device. (parent of devfreq) 112 * @devfreq: The devfreq object. 113 * @nb: The notifier block to be unregistered. 114 @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); 115 116 /** 117 * devm_devfreq_unregister_notifier() 118 - - Resource-managed devfreq_unregister_notifier() 119 + * - Resource-managed devfreq_unregister_notifier() 120 * @dev: The devfreq user device. (parent of devfreq) 121 * @devfreq: The devfreq object. 122 * @nb: The notifier block to be unregistered. 123 -- 124 2.24.1 125 126The entire process only took a few minutes. Of course, I then found that 127somebody else had fixed it in a separate tree, highlighting another lesson: 128always check linux-next to see if a problem has been fixed before you dig 129into it. 130 131Other fixes will take longer, especially those relating to structure 132members or function parameters that lack documentation. In such cases, it 133is necessary to work out what the role of those members or parameters is 134and describe them correctly. Overall, this task gets a little tedious at 135times, but it's highly important. If we can actually eliminate warnings 136from the documentation build, then we can start expecting developers to 137avoid adding new ones. 138 139Languishing kerneldoc comments 140~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 141 142Developers are encouraged to write kerneldoc comments for their code, but 143many of those comments are never pulled into the docs build. That makes 144this information harder to find and, for example, makes Sphinx unable to 145generate links to that documentation. Adding ``kernel-doc`` directives to 146the documentation to bring those comments in can help the community derive 147the full value of the work that has gone into creating them. 148 149The ``scripts/find-unused-docs.sh`` tool can be used to find these 150overlooked comments. 151 152Note that the most value comes from pulling in the documentation for 153exported functions and data structures. Many subsystems also have 154kerneldoc comments for internal use; those should not be pulled into the 155documentation build unless they are placed in a document that is 156specifically aimed at developers working within the relevant subsystem. 157 158 159Typo fixes 160~~~~~~~~~~ 161 162Fixing typographical or formatting errors in the documentation is a quick 163way to figure out how to create and send patches, and it is a useful 164service. I am always willing to accept such patches. That said, once you 165have fixed a few, please consider moving on to more advanced tasks, leaving 166some typos for the next beginner to address. 167 168Please note that some things are *not* typos and should not be "fixed": 169 170 - Both American and British English spellings are allowed within the 171 kernel documentation. There is no need to fix one by replacing it with 172 the other. 173 174 - The question of whether a period should be followed by one or two spaces 175 is not to be debated in the context of kernel documentation. Other 176 areas of rational disagreement, such as the "Oxford comma", are also 177 off-topic here. 178 179As with any patch to any project, please consider whether your change is 180really making things better. 181 182Ancient documentation 183~~~~~~~~~~~~~~~~~~~~~ 184 185Some kernel documentation is current, maintained, and useful. Some 186documentation is ... not. Dusty, old, and inaccurate documentation can 187mislead readers and casts doubt on our documentation as a whole. Anything 188that can be done to address such problems is more than welcome. 189 190Whenever you are working with a document, please consider whether it is 191current, whether it needs updating, or whether it should perhaps be removed 192altogether. There are a number of warning signs that you can pay attention 193to here: 194 195 - References to 2.x kernels 196 - Pointers to SourceForge repositories 197 - Nothing but typo fixes in the history for several years 198 - Discussion of pre-Git workflows 199 200The best thing to do, of course, would be to bring the documentation 201current, adding whatever information is needed. Such work often requires 202the cooperation of developers familiar with the subsystem in question, of 203course. Developers are often more than willing to cooperate with people 204working to improve the documentation when asked nicely, and when their 205answers are listened to and acted upon. 206 207Some documentation is beyond hope; we occasionally find documents that 208refer to code that was removed from the kernel long ago, for example. 209There is surprising resistance to removing obsolete documentation, but we 210should do that anyway. Extra cruft in our documentation helps nobody. 211 212In cases where there is perhaps some useful information in a badly outdated 213document, and you are unable to update it, the best thing to do may be to 214add a warning at the beginning. The following text is recommended:: 215 216 .. warning :: 217 This document is outdated and in need of attention. Please use 218 this information with caution, and please consider sending patches 219 to update it. 220 221That way, at least our long-suffering readers have been warned that the 222document may lead them astray. 223 224Documentation coherency 225~~~~~~~~~~~~~~~~~~~~~~~ 226 227The old-timers around here will remember the Linux books that showed up on 228the shelves in the 1990s. They were simply collections of documentation 229files scrounged from various locations on the net. The books have (mostly) 230improved since then, but the kernel's documentation is still mostly built 231on that model. It is thousands of files, almost each of which was written 232in isolation from all of the others. We don't have a coherent body of 233kernel documentation; we have thousands of individual documents. 234 235We have been trying to improve the situation through the creation of 236a set of "books" that group documentation for specific readers. These 237include: 238 239 - :doc:`../admin-guide/index` 240 - :doc:`../core-api/index` 241 - :doc:`../driver-api/index` 242 - :doc:`../userspace-api/index` 243 244As well as this book on documentation itself. 245 246Moving documents into the appropriate books is an important task and needs 247to continue. There are a couple of challenges associated with this work, 248though. Moving documentation files creates short-term pain for the people 249who work with those files; they are understandably unenthusiastic about 250such changes. Usually the case can be made to move a document once; we 251really don't want to keep shifting them around, though. 252 253Even when all documents are in the right place, though, we have only 254managed to turn a big pile into a group of smaller piles. The work of 255trying to knit all of those documents together into a single whole has not 256yet begun. If you have bright ideas on how we could proceed on that front, 257we would be more than happy to hear them. 258 259Stylesheet improvements 260~~~~~~~~~~~~~~~~~~~~~~~ 261 262With the adoption of Sphinx we have much nicer-looking HTML output than we 263once did. But it could still use a lot of improvement; Donald Knuth and 264Edward Tufte would be unimpressed. That requires tweaking our stylesheets 265to create more typographically sound, accessible, and readable output. 266 267Be warned: if you take on this task you are heading into classic bikeshed 268territory. Expect a lot of opinions and discussion for even relatively 269obvious changes. That is, alas, the nature of the world we live in. 270 271Non-LaTeX PDF build 272~~~~~~~~~~~~~~~~~~~ 273 274This is a decidedly nontrivial task for somebody with a lot of time and 275Python skills. The Sphinx toolchain is relatively small and well 276contained; it is easy to add to a development system. But building PDF or 277EPUB output requires installing LaTeX, which is anything but small or well 278contained. That would be a nice thing to eliminate. 279 280The original hope had been to use the rst2pdf tool (https://rst2pdf.org/) 281for PDF generation, but it turned out to not be up to the task. 282Development work on rst2pdf seems to have picked up again in recent times, 283though, which is a hopeful sign. If a suitably motivated developer were to 284work with that project to make rst2pdf work with the kernel documentation 285build, the world would be eternally grateful. 286 287Write more documentation 288~~~~~~~~~~~~~~~~~~~~~~~~ 289 290Naturally, there are massive parts of the kernel that are severely 291underdocumented. If you have the knowledge to document a specific kernel 292subsystem and the desire to do so, please do not hesitate to do some 293writing and contribute the result to the kernel. Untold numbers of kernel 294developers and users will thank you. 295