Lines Matching +full:documentation +full:- +full:service
1 .. SPDX-License-Identifier: GPL-2.0
3 How to help improve kernel documentation
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
12 Unfortunately, the kernel's documentation currently falls far short of what
16 Kernel documentation improvements can be made by developers at a variety of
19 documentation maintainer's list of tasks that most urgently need to be
22 The documentation TODO list
23 ---------------------------
26 documentation to where it should be. This list contains a number of
28 improve the documentation, please do not hold back!
33 The documentation build currently spews out an unbelievable number of
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
43 Warnings from the documentation build almost always point at a real
45 and fixing it at its source. For this reason, patches fixing documentation
49 Another important point is that documentation warnings are often created by
50 problems in kerneldoc comments in C code. While the documentation
52 documentation tree is often not the right one to actually carry those
55 For example, in a documentation build I grabbed a pair of warnings nearly
59 - Resource-managed devfreq_register_notifier()
61 - Resource-managed devfreq_unregister_notifier()
70 - Resource-managed devfreq_register_notifier()
89 resulting in these doc-build warnings:
92 - Resource-managed devfreq_register_notifier()
94 - Resource-managed devfreq_unregister_notifier()
98 Signed-off-by: Jonathan Corbet <corbet@lwn.net>
99 ---
100 drivers/devfreq/devfreq.c | 4 ++--
101 1 file changed, 2 insertions(+), 2 deletions(-)
103 diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c
105 --- a/drivers/devfreq/devfreq.c
107 @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res)
111 - - Resource-managed devfreq_register_notifier()
112 + * - Resource-managed devfreq_register_notifier()
116 @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);
120 - - Resource-managed devfreq_unregister_notifier()
121 + * - Resource-managed devfreq_unregister_notifier()
125 --
130 always check linux-next to see if a problem has been fixed before you dig
134 members or function parameters that lack documentation. In such cases, it
138 from the documentation build, then we can start expecting developers to
141 In addition to warnings from the regular documentation build, you can also
142 run ``make refcheckdocs`` to find references to nonexistent documentation
151 generate links to that documentation. Adding ``kernel-doc`` directives to
152 the documentation to bring those comments in can help the community derive
155 The ``scripts/find-unused-docs.sh`` tool can be used to find these
158 Note that the most value comes from pulling in the documentation for
161 documentation build unless they are placed in a document that is
168 Fixing typographical or formatting errors in the documentation is a quick
170 service. I am always willing to accept such patches. That said, once you
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
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
183 off-topic here.
188 Ancient documentation
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
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
206 The best thing to do, of course, would be to bring the documentation
210 working to improve the documentation when asked nicely, and when their
213 Some documentation is beyond hope; we occasionally find documents that
215 There is surprising resistance to removing obsolete documentation, but we
216 should do that anyway. Extra cruft in our documentation helps nobody.
227 That way, at least our long-suffering readers have been warned that the
230 Documentation coherency
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
236 improved since then, but the kernel's documentation is still mostly built
239 kernel documentation; we have thousands of individual documents.
242 a set of "books" that group documentation for specific readers. These
245 - Documentation/admin-guide/index.rst
246 - Documentation/core-api/index.rst
247 - Documentation/driver-api/index.rst
248 - Documentation/userspace-api/index.rst
250 As well as this book on documentation itself.
254 though. Moving documentation files creates short-term pain for the people
268 With the adoption of Sphinx we have much nicer-looking HTML output than we
277 Non-LaTeX PDF build
290 work with that project to make rst2pdf work with the kernel documentation
293 Write more documentation