Commit | Line | Data |
---|---|---|
d96574b0 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
ff1e81a7 | 2 | |
d96574b0 JC |
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, | |
f1a69399 KK |
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:: | |
d96574b0 JC |
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 | Languishing kerneldoc comments | |
142 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
143 | ||
144 | Developers are encouraged to write kerneldoc comments for their code, but | |
145 | many of those comments are never pulled into the docs build. That makes | |
146 | this information harder to find and, for example, makes Sphinx unable to | |
147 | generate links to that documentation. Adding ``kernel-doc`` directives to | |
148 | the documentation to bring those comments in can help the community derive | |
149 | the full value of the work that has gone into creating them. | |
150 | ||
151 | The ``scripts/find-unused-docs.sh`` tool can be used to find these | |
152 | overlooked comments. | |
153 | ||
154 | Note that the most value comes from pulling in the documentation for | |
155 | exported functions and data structures. Many subsystems also have | |
156 | kerneldoc comments for internal use; those should not be pulled into the | |
157 | documentation build unless they are placed in a document that is | |
158 | specifically aimed at developers working within the relevant subsystem. | |
159 | ||
160 | ||
161 | Typo fixes | |
162 | ~~~~~~~~~~ | |
163 | ||
164 | Fixing typographical or formatting errors in the documentation is a quick | |
165 | way to figure out how to create and send patches, and it is a useful | |
166 | service. I am always willing to accept such patches. That said, once you | |
167 | have fixed a few, please consider moving on to more advanced tasks, leaving | |
168 | some typos for the next beginner to address. | |
169 | ||
170 | Please note that some things are *not* typos and should not be "fixed": | |
171 | ||
172 | - Both American and British English spellings are allowed within the | |
173 | kernel documentation. There is no need to fix one by replacing it with | |
174 | the other. | |
175 | ||
176 | - The question of whether a period should be followed by one or two spaces | |
177 | is not to be debated in the context of kernel documentation. Other | |
178 | areas of rational disagreement, such as the "Oxford comma", are also | |
179 | off-topic here. | |
180 | ||
181 | As with any patch to any project, please consider whether your change is | |
182 | really making things better. | |
183 | ||
184 | Ancient documentation | |
185 | ~~~~~~~~~~~~~~~~~~~~~ | |
186 | ||
187 | Some kernel documentation is current, maintained, and useful. Some | |
188 | documentation is ... not. Dusty, old, and inaccurate documentation can | |
189 | mislead readers and casts doubt on our documentation as a whole. Anything | |
190 | that can be done to address such problems is more than welcome. | |
191 | ||
192 | Whenever you are working with a document, please consider whether it is | |
193 | current, whether it needs updating, or whether it should perhaps be removed | |
194 | altogether. There are a number of warning signs that you can pay attention | |
195 | to here: | |
196 | ||
197 | - References to 2.x kernels | |
198 | - Pointers to SourceForge repositories | |
199 | - Nothing but typo fixes in the history for several years | |
200 | - Discussion of pre-Git workflows | |
201 | ||
202 | The best thing to do, of course, would be to bring the documentation | |
203 | current, adding whatever information is needed. Such work often requires | |
204 | the cooperation of developers familiar with the subsystem in question, of | |
205 | course. Developers are often more than willing to cooperate with people | |
206 | working to improve the documentation when asked nicely, and when their | |
207 | answers are listened to and acted upon. | |
208 | ||
209 | Some documentation is beyond hope; we occasionally find documents that | |
210 | refer to code that was removed from the kernel long ago, for example. | |
211 | There is surprising resistance to removing obsolete documentation, but we | |
212 | should do that anyway. Extra cruft in our documentation helps nobody. | |
213 | ||
214 | In cases where there is perhaps some useful information in a badly outdated | |
215 | document, and you are unable to update it, the best thing to do may be to | |
216 | add a warning at the beginning. The following text is recommended:: | |
217 | ||
218 | .. warning :: | |
219 | This document is outdated and in need of attention. Please use | |
220 | this information with caution, and please consider sending patches | |
221 | to update it. | |
222 | ||
223 | That way, at least our long-suffering readers have been warned that the | |
224 | document may lead them astray. | |
225 | ||
226 | Documentation coherency | |
227 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
228 | ||
229 | The old-timers around here will remember the Linux books that showed up on | |
230 | the shelves in the 1990s. They were simply collections of documentation | |
231 | files scrounged from various locations on the net. The books have (mostly) | |
232 | improved since then, but the kernel's documentation is still mostly built | |
233 | on that model. It is thousands of files, almost each of which was written | |
234 | in isolation from all of the others. We don't have a coherent body of | |
235 | kernel documentation; we have thousands of individual documents. | |
236 | ||
237 | We have been trying to improve the situation through the creation of | |
238 | a set of "books" that group documentation for specific readers. These | |
239 | include: | |
240 | ||
fd88d2e5 MCC |
241 | - Documentation/admin-guide/index.rst |
242 | - Documentation/core-api/index.rst | |
243 | - Documentation/driver-api/index.rst | |
244 | - Documentation/userspace-api/index.rst | |
d96574b0 JC |
245 | |
246 | As well as this book on documentation itself. | |
247 | ||
248 | Moving documents into the appropriate books is an important task and needs | |
249 | to continue. There are a couple of challenges associated with this work, | |
250 | though. Moving documentation files creates short-term pain for the people | |
251 | who work with those files; they are understandably unenthusiastic about | |
252 | such changes. Usually the case can be made to move a document once; we | |
253 | really don't want to keep shifting them around, though. | |
254 | ||
255 | Even when all documents are in the right place, though, we have only | |
256 | managed to turn a big pile into a group of smaller piles. The work of | |
257 | trying to knit all of those documents together into a single whole has not | |
258 | yet begun. If you have bright ideas on how we could proceed on that front, | |
259 | we would be more than happy to hear them. | |
260 | ||
261 | Stylesheet improvements | |
262 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
263 | ||
264 | With the adoption of Sphinx we have much nicer-looking HTML output than we | |
265 | once did. But it could still use a lot of improvement; Donald Knuth and | |
266 | Edward Tufte would be unimpressed. That requires tweaking our stylesheets | |
267 | to create more typographically sound, accessible, and readable output. | |
268 | ||
269 | Be warned: if you take on this task you are heading into classic bikeshed | |
270 | territory. Expect a lot of opinions and discussion for even relatively | |
271 | obvious changes. That is, alas, the nature of the world we live in. | |
272 | ||
273 | Non-LaTeX PDF build | |
274 | ~~~~~~~~~~~~~~~~~~~ | |
275 | ||
276 | This is a decidedly nontrivial task for somebody with a lot of time and | |
277 | Python skills. The Sphinx toolchain is relatively small and well | |
278 | contained; it is easy to add to a development system. But building PDF or | |
279 | EPUB output requires installing LaTeX, which is anything but small or well | |
280 | contained. That would be a nice thing to eliminate. | |
281 | ||
282 | The original hope had been to use the rst2pdf tool (https://rst2pdf.org/) | |
283 | for PDF generation, but it turned out to not be up to the task. | |
284 | Development work on rst2pdf seems to have picked up again in recent times, | |
285 | though, which is a hopeful sign. If a suitably motivated developer were to | |
286 | work with that project to make rst2pdf work with the kernel documentation | |
287 | build, the world would be eternally grateful. | |
288 | ||
289 | Write more documentation | |
290 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
291 | ||
292 | Naturally, there are massive parts of the kernel that are severely | |
293 | underdocumented. If you have the knowledge to document a specific kernel | |
294 | subsystem and the desire to do so, please do not hesitate to do some | |
295 | writing and contribute the result to the kernel. Untold numbers of kernel | |
296 | developers and users will thank you. |