Documentation/doc-guide/contributing.rst

   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 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
 241  - Documentation/admin-guide/index.rst
 242  - Documentation/core-api/index.rst
 243  - Documentation/driver-api/index.rst
 244  - Documentation/userspace-api/index.rst
 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.