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