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