1.. SPDX-License-Identifier: GPL-2.0
2
3How to help improve kernel documentation
4========================================
5
6Documentation is an important part of any software-development project.
7Good documentation helps to bring new developers in and helps established
8developers work more effectively.  Without top-quality documentation, a lot
9of time is wasted in reverse-engineering the code and making avoidable
10mistakes.
11
12Unfortunately, the kernel's documentation currently falls far short of what
13it needs to be to support a project of this size and importance.
14
15This guide is for contributors who would like to improve that situation.
16Kernel documentation improvements can be made by developers at a variety of
17skill levels; they are a relatively easy way to learn the kernel process in
18general and find a place in the community.  The bulk of what follows is the
19documentation maintainer's list of tasks that most urgently need to be
20done.
21
22The documentation TODO list
23---------------------------
24
25There is an endless list of tasks that need to be carried out to get our
26documentation to where it should be.  This list contains a number of
27important items, but is far from exhaustive; if you see a different way to
28improve the documentation, please do not hold back!
29
30Addressing warnings
31~~~~~~~~~~~~~~~~~~~
32
33The documentation build currently spews out an unbelievable number of
34warnings.  When you have that many, you might as well have none at all;
35people ignore them, and they will never notice when their work adds new
36ones.  For this reason, eliminating warnings is one of the highest-priority
37tasks on the documentation TODO list.  The task itself is reasonably
38straightforward, but it must be approached in the right way to be
39successful.
40
41Warnings issued by a compiler for C code can often be dismissed as false
42positives, leading to patches aimed at simply shutting the compiler up.
43Warnings from the documentation build almost always point at a real
44problem; making those warnings go away requires understanding the problem
45and fixing it at its source.  For this reason, patches fixing documentation
46warnings should probably not say "fix a warning" in the changelog title;
47they should indicate the real problem that has been fixed.
48
49Another important point is that documentation warnings are often created by
50problems in kerneldoc comments in C code.  While the documentation
51maintainer appreciates being copied on fixes for these warnings, the
52documentation tree is often not the right one to actually carry those
53fixes; they should go to the maintainer of the subsystem in question.
54
55For example, in a documentation build I grabbed a pair of warnings nearly
56at 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
65A quick look at the source file named above turned up a couple of kerneldoc
66comments 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
77The problem is the missing "*", which confuses the build system's
78simplistic idea of what C comment blocks look like.  This problem had been
79present since that comment was added in 2016 — a full four years.  Fixing
80it was a matter of adding the missing asterisks.  A quick look at the
81history for that file showed what the normal format for subject lines is,
82and ``scripts/get_maintainer.pl`` told me who should receive it.  The
83resulting 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
127The entire process only took a few minutes.  Of course, I then found that
128somebody else had fixed it in a separate tree, highlighting another lesson:
129always check linux-next to see if a problem has been fixed before you dig
130into it.
131
132Other fixes will take longer, especially those relating to structure
133members or function parameters that lack documentation.  In such cases, it
134is necessary to work out what the role of those members or parameters is
135and describe them correctly.  Overall, this task gets a little tedious at
136times, but it's highly important.  If we can actually eliminate warnings
137from the documentation build, then we can start expecting developers to
138avoid adding new ones.
139
140Languishing kerneldoc comments
141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142
143Developers are encouraged to write kerneldoc comments for their code, but
144many of those comments are never pulled into the docs build.  That makes
145this information harder to find and, for example, makes Sphinx unable to
146generate links to that documentation.  Adding ``kernel-doc`` directives to
147the documentation to bring those comments in can help the community derive
148the full value of the work that has gone into creating them.
149
150The ``scripts/find-unused-docs.sh`` tool can be used to find these
151overlooked comments.
152
153Note that the most value comes from pulling in the documentation for
154exported functions and data structures.  Many subsystems also have
155kerneldoc comments for internal use; those should not be pulled into the
156documentation build unless they are placed in a document that is
157specifically aimed at developers working within the relevant subsystem.
158
159
160Typo fixes
161~~~~~~~~~~
162
163Fixing typographical or formatting errors in the documentation is a quick
164way to figure out how to create and send patches, and it is a useful
165service.  I am always willing to accept such patches.  That said, once you
166have fixed a few, please consider moving on to more advanced tasks, leaving
167some typos for the next beginner to address.
168
169Please 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
180As with any patch to any project, please consider whether your change is
181really making things better.
182
183Ancient documentation
184~~~~~~~~~~~~~~~~~~~~~
185
186Some kernel documentation is current, maintained, and useful.  Some
187documentation is ... not.  Dusty, old, and inaccurate documentation can
188mislead readers and casts doubt on our documentation as a whole.  Anything
189that can be done to address such problems is more than welcome.
190
191Whenever you are working with a document, please consider whether it is
192current, whether it needs updating, or whether it should perhaps be removed
193altogether.  There are a number of warning signs that you can pay attention
194to 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
201The best thing to do, of course, would be to bring the documentation
202current, adding whatever information is needed.  Such work often requires
203the cooperation of developers familiar with the subsystem in question, of
204course.  Developers are often more than willing to cooperate with people
205working to improve the documentation when asked nicely, and when their
206answers are listened to and acted upon.
207
208Some documentation is beyond hope; we occasionally find documents that
209refer to code that was removed from the kernel long ago, for example.
210There is surprising resistance to removing obsolete documentation, but we
211should do that anyway.  Extra cruft in our documentation helps nobody.
212
213In cases where there is perhaps some useful information in a badly outdated
214document, and you are unable to update it, the best thing to do may be to
215add 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
222That way, at least our long-suffering readers have been warned that the
223document may lead them astray.
224
225Documentation coherency
226~~~~~~~~~~~~~~~~~~~~~~~
227
228The old-timers around here will remember the Linux books that showed up on
229the shelves in the 1990s.  They were simply collections of documentation
230files scrounged from various locations on the net.  The books have (mostly)
231improved since then, but the kernel's documentation is still mostly built
232on that model.  It is thousands of files, almost each of which was written
233in isolation from all of the others.  We don't have a coherent body of
234kernel documentation; we have thousands of individual documents.
235
236We have been trying to improve the situation through the creation of
237a set of "books" that group documentation for specific readers.  These
238include:
239
240 - Documentation/admin-guide/index.rst
241 - Documentation/core-api/index.rst
242 - Documentation/driver-api/index.rst
243 - Documentation/userspace-api/index.rst
244
245As well as this book on documentation itself.
246
247Moving documents into the appropriate books is an important task and needs
248to continue.  There are a couple of challenges associated with this work,
249though.  Moving documentation files creates short-term pain for the people
250who work with those files; they are understandably unenthusiastic about
251such changes.  Usually the case can be made to move a document once; we
252really don't want to keep shifting them around, though.
253
254Even when all documents are in the right place, though, we have only
255managed to turn a big pile into a group of smaller piles.  The work of
256trying to knit all of those documents together into a single whole has not
257yet begun.  If you have bright ideas on how we could proceed on that front,
258we would be more than happy to hear them.
259
260Stylesheet improvements
261~~~~~~~~~~~~~~~~~~~~~~~
262
263With the adoption of Sphinx we have much nicer-looking HTML output than we
264once did.  But it could still use a lot of improvement; Donald Knuth and
265Edward Tufte would be unimpressed.  That requires tweaking our stylesheets
266to create more typographically sound, accessible, and readable output.
267
268Be warned: if you take on this task you are heading into classic bikeshed
269territory.  Expect a lot of opinions and discussion for even relatively
270obvious changes.  That is, alas, the nature of the world we live in.
271
272Non-LaTeX PDF build
273~~~~~~~~~~~~~~~~~~~
274
275This is a decidedly nontrivial task for somebody with a lot of time and
276Python skills.  The Sphinx toolchain is relatively small and well
277contained; it is easy to add to a development system.  But building PDF or
278EPUB output requires installing LaTeX, which is anything but small or well
279contained.  That would be a nice thing to eliminate.
280
281The original hope had been to use the rst2pdf tool (https://rst2pdf.org/)
282for PDF generation, but it turned out to not be up to the task.
283Development work on rst2pdf seems to have picked up again in recent times,
284though, which is a hopeful sign.  If a suitably motivated developer were to
285work with that project to make rst2pdf work with the kernel documentation
286build, the world would be eternally grateful.
287
288Write more documentation
289~~~~~~~~~~~~~~~~~~~~~~~~
290
291Naturally, there are massive parts of the kernel that are severely
292underdocumented.  If you have the knowledge to document a specific kernel
293subsystem and the desire to do so, please do not hesitate to do some
294writing and contribute the result to the kernel.  Untold numbers of kernel
295developers and users will thank you.
296