| 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 <[email protected]> |
| 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 ``tools/docs/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. |