| .. SPDX-License-Identifier: GPL-2.0 |
| |
| How to help improve kernel documentation |
| ======================================== |
| |
| Documentation is an important part of any software-development project. |
| Good documentation helps to bring new developers in and helps established |
| developers work more effectively. Without top-quality documentation, a lot |
| of time is wasted in reverse-engineering the code and making avoidable |
| mistakes. |
| |
| Unfortunately, the kernel's documentation currently falls far short of what |
| it needs to be to support a project of this size and importance. |
| |
| This guide is for contributors who would like to improve that situation. |
| Kernel documentation improvements can be made by developers at a variety of |
| skill levels; they are a relatively easy way to learn the kernel process in |
| general and find a place in the community. The bulk of what follows is the |
| documentation maintainer's list of tasks that most urgently need to be |
| done. |
| |
| The documentation TODO list |
| --------------------------- |
| |
| There is an endless list of tasks that need to be carried out to get our |
| documentation to where it should be. This list contains a number of |
| important items, but is far from exhaustive; if you see a different way to |
| improve the documentation, please do not hold back! |
| |
| Addressing warnings |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| The documentation build currently spews out an unbelievable number of |
| warnings. When you have that many, you might as well have none at all; |
| people ignore them, and they will never notice when their work adds new |
| ones. For this reason, eliminating warnings is one of the highest-priority |
| tasks on the documentation TODO list. The task itself is reasonably |
| straightforward, but it must be approached in the right way to be |
| successful. |
| |
| Warnings issued by a compiler for C code can often be dismissed as false |
| positives, leading to patches aimed at simply shutting the compiler up. |
| Warnings from the documentation build almost always point at a real |
| problem; making those warnings go away requires understanding the problem |
| and fixing it at its source. For this reason, patches fixing documentation |
| warnings should probably not say "fix a warning" in the changelog title; |
| they should indicate the real problem that has been fixed. |
| |
| Another important point is that documentation warnings are often created by |
| problems in kerneldoc comments in C code. While the documentation |
| maintainer appreciates being copied on fixes for these warnings, the |
| documentation tree is often not the right one to actually carry those |
| fixes; they should go to the maintainer of the subsystem in question. |
| |
| For example, in a documentation build I grabbed a pair of warnings nearly |
| at random:: |
| |
| ./drivers/devfreq/devfreq.c:1818: warning: bad line: |
| - Resource-managed devfreq_register_notifier() |
| ./drivers/devfreq/devfreq.c:1854: warning: bad line: |
| - Resource-managed devfreq_unregister_notifier() |
| |
| (The lines were split for readability). |
| |
| A quick look at the source file named above turned up a couple of kerneldoc |
| comments that look like this:: |
| |
| /** |
| * devm_devfreq_register_notifier() |
| - Resource-managed devfreq_register_notifier() |
| * @dev: The devfreq user device. (parent of devfreq) |
| * @devfreq: The devfreq object. |
| * @nb: The notifier block to be unregistered. |
| * @list: DEVFREQ_TRANSITION_NOTIFIER. |
| */ |
| |
| The problem is the missing "*", which confuses the build system's |
| simplistic idea of what C comment blocks look like. This problem had been |
| present since that comment was added in 2016 — a full four years. Fixing |
| it was a matter of adding the missing asterisks. A quick look at the |
| history for that file showed what the normal format for subject lines is, |
| and ``scripts/get_maintainer.pl`` told me who should receive it. The |
| resulting patch looked like this:: |
| |
| [PATCH] PM / devfreq: Fix two malformed kerneldoc comments |
| |
| Two kerneldoc comments in devfreq.c fail to adhere to the required format, |
| resulting in these doc-build warnings: |
| |
| ./drivers/devfreq/devfreq.c:1818: warning: bad line: |
| - Resource-managed devfreq_register_notifier() |
| ./drivers/devfreq/devfreq.c:1854: warning: bad line: |
| - Resource-managed devfreq_unregister_notifier() |
| |
| Add a couple of missing asterisks and make kerneldoc a little happier. |
| |
| Signed-off-by: Jonathan Corbet <corbet@lwn.net> |
| --- |
| drivers/devfreq/devfreq.c | 4 ++-- |
| 1 file changed, 2 insertions(+), 2 deletions(-) |
| |
| diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c |
| index 57f6944d65a6..00c9b80b3d33 100644 |
| --- a/drivers/devfreq/devfreq.c |
| +++ b/drivers/devfreq/devfreq.c |
| @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res) |
| |
| /** |
| * devm_devfreq_register_notifier() |
| - - Resource-managed devfreq_register_notifier() |
| + * - Resource-managed devfreq_register_notifier() |
| * @dev: The devfreq user device. (parent of devfreq) |
| * @devfreq: The devfreq object. |
| * @nb: The notifier block to be unregistered. |
| @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); |
| |
| /** |
| * devm_devfreq_unregister_notifier() |
| - - Resource-managed devfreq_unregister_notifier() |
| + * - Resource-managed devfreq_unregister_notifier() |
| * @dev: The devfreq user device. (parent of devfreq) |
| * @devfreq: The devfreq object. |
| * @nb: The notifier block to be unregistered. |
| -- |
| 2.24.1 |
| |
| The entire process only took a few minutes. Of course, I then found that |
| somebody else had fixed it in a separate tree, highlighting another lesson: |
| always check linux-next to see if a problem has been fixed before you dig |
| into it. |
| |
| Other fixes will take longer, especially those relating to structure |
| members or function parameters that lack documentation. In such cases, it |
| is necessary to work out what the role of those members or parameters is |
| and describe them correctly. Overall, this task gets a little tedious at |
| times, but it's highly important. If we can actually eliminate warnings |
| from the documentation build, then we can start expecting developers to |
| avoid adding new ones. |
| |
| Languishing kerneldoc comments |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Developers are encouraged to write kerneldoc comments for their code, but |
| many of those comments are never pulled into the docs build. That makes |
| this information harder to find and, for example, makes Sphinx unable to |
| generate links to that documentation. Adding ``kernel-doc`` directives to |
| the documentation to bring those comments in can help the community derive |
| the full value of the work that has gone into creating them. |
| |
| The ``scripts/find-unused-docs.sh`` tool can be used to find these |
| overlooked comments. |
| |
| Note that the most value comes from pulling in the documentation for |
| exported functions and data structures. Many subsystems also have |
| kerneldoc comments for internal use; those should not be pulled into the |
| documentation build unless they are placed in a document that is |
| specifically aimed at developers working within the relevant subsystem. |
| |
| |
| Typo fixes |
| ~~~~~~~~~~ |
| |
| Fixing typographical or formatting errors in the documentation is a quick |
| way to figure out how to create and send patches, and it is a useful |
| service. I am always willing to accept such patches. That said, once you |
| have fixed a few, please consider moving on to more advanced tasks, leaving |
| some typos for the next beginner to address. |
| |
| Please note that some things are *not* typos and should not be "fixed": |
| |
| - Both American and British English spellings are allowed within the |
| kernel documentation. There is no need to fix one by replacing it with |
| the other. |
| |
| - The question of whether a period should be followed by one or two spaces |
| is not to be debated in the context of kernel documentation. Other |
| areas of rational disagreement, such as the "Oxford comma", are also |
| off-topic here. |
| |
| As with any patch to any project, please consider whether your change is |
| really making things better. |
| |
| Ancient documentation |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| Some kernel documentation is current, maintained, and useful. Some |
| documentation is ... not. Dusty, old, and inaccurate documentation can |
| mislead readers and casts doubt on our documentation as a whole. Anything |
| that can be done to address such problems is more than welcome. |
| |
| Whenever you are working with a document, please consider whether it is |
| current, whether it needs updating, or whether it should perhaps be removed |
| altogether. There are a number of warning signs that you can pay attention |
| to here: |
| |
| - References to 2.x kernels |
| - Pointers to SourceForge repositories |
| - Nothing but typo fixes in the history for several years |
| - Discussion of pre-Git workflows |
| |
| The best thing to do, of course, would be to bring the documentation |
| current, adding whatever information is needed. Such work often requires |
| the cooperation of developers familiar with the subsystem in question, of |
| course. Developers are often more than willing to cooperate with people |
| working to improve the documentation when asked nicely, and when their |
| answers are listened to and acted upon. |
| |
| Some documentation is beyond hope; we occasionally find documents that |
| refer to code that was removed from the kernel long ago, for example. |
| There is surprising resistance to removing obsolete documentation, but we |
| should do that anyway. Extra cruft in our documentation helps nobody. |
| |
| In cases where there is perhaps some useful information in a badly outdated |
| document, and you are unable to update it, the best thing to do may be to |
| add a warning at the beginning. The following text is recommended:: |
| |
| .. warning :: |
| This document is outdated and in need of attention. Please use |
| this information with caution, and please consider sending patches |
| to update it. |
| |
| That way, at least our long-suffering readers have been warned that the |
| document may lead them astray. |
| |
| Documentation coherency |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| The old-timers around here will remember the Linux books that showed up on |
| the shelves in the 1990s. They were simply collections of documentation |
| files scrounged from various locations on the net. The books have (mostly) |
| improved since then, but the kernel's documentation is still mostly built |
| on that model. It is thousands of files, almost each of which was written |
| in isolation from all of the others. We don't have a coherent body of |
| kernel documentation; we have thousands of individual documents. |
| |
| We have been trying to improve the situation through the creation of |
| a set of "books" that group documentation for specific readers. These |
| include: |
| |
| - :doc:`../admin-guide/index` |
| - :doc:`../core-api/index` |
| - :doc:`../driver-api/index` |
| - :doc:`../userspace-api/index` |
| |
| As well as this book on documentation itself. |
| |
| Moving documents into the appropriate books is an important task and needs |
| to continue. There are a couple of challenges associated with this work, |
| though. Moving documentation files creates short-term pain for the people |
| who work with those files; they are understandably unenthusiastic about |
| such changes. Usually the case can be made to move a document once; we |
| really don't want to keep shifting them around, though. |
| |
| Even when all documents are in the right place, though, we have only |
| managed to turn a big pile into a group of smaller piles. The work of |
| trying to knit all of those documents together into a single whole has not |
| yet begun. If you have bright ideas on how we could proceed on that front, |
| we would be more than happy to hear them. |
| |
| Stylesheet improvements |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| With the adoption of Sphinx we have much nicer-looking HTML output than we |
| once did. But it could still use a lot of improvement; Donald Knuth and |
| Edward Tufte would be unimpressed. That requires tweaking our stylesheets |
| to create more typographically sound, accessible, and readable output. |
| |
| Be warned: if you take on this task you are heading into classic bikeshed |
| territory. Expect a lot of opinions and discussion for even relatively |
| obvious changes. That is, alas, the nature of the world we live in. |
| |
| Non-LaTeX PDF build |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| This is a decidedly nontrivial task for somebody with a lot of time and |
| Python skills. The Sphinx toolchain is relatively small and well |
| contained; it is easy to add to a development system. But building PDF or |
| EPUB output requires installing LaTeX, which is anything but small or well |
| contained. That would be a nice thing to eliminate. |
| |
| The original hope had been to use the rst2pdf tool (https://rst2pdf.org/) |
| for PDF generation, but it turned out to not be up to the task. |
| Development work on rst2pdf seems to have picked up again in recent times, |
| though, which is a hopeful sign. If a suitably motivated developer were to |
| work with that project to make rst2pdf work with the kernel documentation |
| build, the world would be eternally grateful. |
| |
| Write more documentation |
| ~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Naturally, there are massive parts of the kernel that are severely |
| underdocumented. If you have the knowledge to document a specific kernel |
| subsystem and the desire to do so, please do not hesitate to do some |
| writing and contribute the result to the kernel. Untold numbers of kernel |
| developers and users will thank you. |
