Lines Matching +full:quality +full:- +full:of +full:- +full:service
1 .. SPDX-License-Identifier: GPL-2.0
6 Documentation is an important part of any software-development project.
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
13 it needs to be to support a project of this size and importance.
16 Kernel documentation improvements can be made by developers at a variety of
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
23 ---------------------------
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
33 The documentation build currently spews out an unbelievable number of
36 ones. For this reason, eliminating warnings is one of the highest-priority
53 fixes; they should go to the maintainer of the subsystem in question.
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()
65 A quick look at the source file named above turned up a couple of kerneldoc
70 - Resource-managed devfreq_register_notifier()
71 * @dev: The devfreq user device. (parent of devfreq)
78 simplistic idea of what C comment blocks look like. This problem had been
80 it was a matter of adding the missing asterisks. A quick look at the
89 resulting in these doc-build warnings:
92 - Resource-managed devfreq_register_notifier()
94 - Resource-managed devfreq_unregister_notifier()
96 Add a couple of missing asterisks and make kerneldoc a little happier.
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()
113 * @dev: The devfreq user device. (parent of devfreq)
116 @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);
120 - - Resource-managed devfreq_unregister_notifier()
121 + * - Resource-managed devfreq_unregister_notifier()
122 * @dev: The devfreq user device. (parent of devfreq)
125 --
128 The entire process only took a few minutes. Of course, I then found that
130 always check linux-next to see if a problem has been fixed before you dig
135 is necessary to work out what the role of those members or parameters is
149 many of those comments are never pulled into the docs build. That makes
151 generate links to that documentation. Adding ``kernel-doc`` directives to
153 the full value of the work that has gone into creating them.
155 The ``scripts/find-unused-docs.sh`` tool can be used to find these
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
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
182 areas of rational disagreement, such as the "Oxford comma", are also
183 off-topic here.
198 altogether. There are a number of warning signs that you can pay attention
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
208 the cooperation of developers familiar with the subsystem in question, of
223 This document is outdated and in need of attention. Please use
227 That way, at least our long-suffering readers have been warned that the
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
237 on that model. It is thousands of files, almost each of which was written
238 in isolation from all of the others. We don't have a coherent body of
239 kernel documentation; we have thousands of individual documents.
241 We have been trying to improve the situation through the creation of
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
253 to continue. There are a couple of challenges associated with this work,
254 though. Moving documentation files creates short-term pain for the people
260 managed to turn a big pile into a group of smaller piles. The work of
261 trying to knit all of those documents together into a single whole has not
268 With the adoption of Sphinx we have much nicer-looking HTML output than we
269 once did. But it could still use a lot of improvement; Donald Knuth and
274 territory. Expect a lot of opinions and discussion for even relatively
275 obvious changes. That is, alas, the nature of the world we live in.
277 Non-LaTeX PDF build
280 This is a decidedly nontrivial task for somebody with a lot of time and
296 Naturally, there are massive parts of the kernel that are severely
299 writing and contribute the result to the kernel. Untold numbers of kernel