Documentation/doc-guide/contributing.rst

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
23 ---------------------------
36 ones.  For this reason, eliminating warnings is one of the highest-priority
42 positives, leading to patches aimed at simply shutting the compiler up.
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
66 comments that look like this::
70 	  - Resource-managed devfreq_register_notifier()
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()
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
151 generate links to that documentation.  Adding ``kernel-doc`` directives to
155 The ``scripts/find-unused-docs.sh`` tool can be used to find these
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
183    off-topic here.
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
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
245  - Documentation/admin-guide/index.rst
246  - Documentation/core-api/index.rst
247  - Documentation/driver-api/index.rst
248  - Documentation/userspace-api/index.rst
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
287 for PDF generation, but it turned out to not be up to the task.
288 Development work on rst2pdf seems to have picked up again in recent times,