| 1 | |
| 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.
|