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