1.. SPDX-License-Identifier: GPL-2.0
2
3.. include:: ../disclaimer-zh_CN.rst
4
5:Original: Documentation/doc-guide/contributing.rst
6
7:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>
8
9如何帮助改进内核文档
10====================
11
12在任何软件开发项目中，文档都是重要组成部分。好的文档有助于引入新的开发人员，
13并帮助已有的开发人员更有效地工作。如果缺少高质量的文档，大量的时间就会浪费在
14代码的逆向工程和犯本可避免的错误上。
15
16不幸的是，内核的文档目前远远不能满足支持如此规模和重要性的项目的需要。
17
18本指南适用于希望帮助改善这种状况的贡献者。内核文档的改进可以由开发者在不同的
19技能层级上进行；这也是一条相对简单可以帮助您了解内核过程并在社区中找到一席之
20地的路径。下面的大部分内容是文档维护人员列出的最迫切需要完成的任务。
21
22文档待办事项列表
23----------------
24
25为了使我们的文档达到应有的水平，需要完成的任务数不胜数。此列表包含许多重要的
26项目，但还远远不够详尽；如果您知道改进文档的其他方法，请不要羞于启齿。
27
28消除警告（WARNING）
29~~~~~~~~~~~~~~~~~~~
30
31文档构建目前出现了数量惊人的警告。虱子多了不痒，债多了不愁；大伙儿忽略了它们，
32他们永远不会注意到他们的工作增加了新的警告。因此，消除警告是文档待办事项列表
33中优先级最高的任务之一。这项任务本身相当简单，但必须以正确的方式进行，才能取
34得成功。
35
36C代码编译器发出的警告常常会被视为误报，从而导致出现了旨在让编译器闭嘴的补丁。
37文档构建中的警告几乎总是指向真正的问题；要消除这些警告，需要理解问题并从源头上
38解决问题。因此，修复文档警告的补丁不应在标题中直接写“修复警告”；它们应该指明
39真正修复的问题。
40
41另一个重点是，文档警告常常由C代码里kernel-doc注释中的问题引起。虽然文档维护
42人员对收到这些修复补丁的副本表示感谢，但是文档树实际上通常并不适合接受这些
43补丁；它们应该被交给相关子系统的维护人员。
44
45例如，在一次文档构建中，我几乎是随意选取了一对警告::
46
47  ./drivers/devfreq/devfreq.c:1818: warning: bad line:
48  	- Resource-managed devfreq_register_notifier()
49  ./drivers/devfreq/devfreq.c:1854: warning: bad line:
50  	- Resource-managed devfreq_unregister_notifier()
51
52（作了断行以便于阅读）
53
54简单看一下上面给出的源文件，会发现几个kernel-doc注释，如下所示::
55
56  /**
57   * devm_devfreq_register_notifier()
58   	- Resource-managed devfreq_register_notifier()
59   * @dev:	The devfreq user device. (parent of devfreq)
60   * @devfreq:	The devfreq object.
61   * @nb:	The notifier block to be unregistered.
62   * @list:	DEVFREQ_TRANSITION_NOTIFIER.
63   */
64
65问题在于缺了一个“*”，这不符合构建系统对C注释块的格式要求。此问题自2016年注释
66被添加以来一直存在——整整四年之久。修复它只需要添加丢失的星号。看一眼该文件的
67历史记录以了解主题行的常规格式是什么样，再使用 ``scripts/get_maintainer.pl``
68来搞清谁应当收到此补丁。生成的补丁如下所示::
69
70  [PATCH] PM / devfreq: Fix two malformed kerneldoc comments
71
72  Two kerneldoc comments in devfreq.c fail to adhere to the required format,
73  resulting in these doc-build warnings:
74
75    ./drivers/devfreq/devfreq.c:1818: warning: bad line:
76  	  - Resource-managed devfreq_register_notifier()
77    ./drivers/devfreq/devfreq.c:1854: warning: bad line:
78  	  - Resource-managed devfreq_unregister_notifier()
79
80  Add a couple of missing asterisks and make kerneldoc a little happier.
81
82  Signed-off-by: Jonathan Corbet <corbet@lwn.net>
83  ---
84   drivers/devfreq/devfreq.c | 4 ++--
85   1 file changed, 2 insertions(+), 2 deletions(-)
86
87  diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c
88  index 57f6944d65a6..00c9b80b3d33 100644
89  --- a/drivers/devfreq/devfreq.c
90  +++ b/drivers/devfreq/devfreq.c
91  @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res)
92
93   /**
94    * devm_devfreq_register_notifier()
95  -	- Resource-managed devfreq_register_notifier()
96  + *	- Resource-managed devfreq_register_notifier()
97    * @dev:	The devfreq user device. (parent of devfreq)
98    * @devfreq:	The devfreq object.
99    * @nb:		The notifier block to be unregistered.
100  @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);
101
102   /**
103    * devm_devfreq_unregister_notifier()
104  -	- Resource-managed devfreq_unregister_notifier()
105  + *	- Resource-managed devfreq_unregister_notifier()
106    * @dev:	The devfreq user device. (parent of devfreq)
107    * @devfreq:	The devfreq object.
108    * @nb:		The notifier block to be unregistered.
109  --
110  2.24.1
111
112整个过程只花了几分钟。当然，我后来发现有人在另一个树中修复了它，这亮出了另一
113个教训：在深入研究问题之前，一定要检查linux-next树，看看问题是否已经修复。
114
115其他修复可能需要更长的时间，尤其是那些与缺少文档的结构体成员或函数参数相关的
116修复。这种情况下，需要找出这些成员或参数的作用，并正确描述它们。总之，这种
117任务有时会有点乏味，但它非常重要。如果我们真的可以从文档构建中消除警告，那么
118我们就可以开始期望开发人员开始注意避免添加新的警告了。
119
120“迷失的”kernel-doc注释
121~~~~~~~~~~~~~~~~~~~~~~
122
123开发者被鼓励去为他们的代码写kernel-doc注释，但是许多注释从未被引入文档构建。
124这使得这些信息更难找到，例如使Sphinx无法生成指向该文档的链接。将 ``kernel-doc``
125指令添加到文档中以引入这些注释可以帮助社区获得为编写注释所做工作的全部价值。
126
127``scripts/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。
128
129请注意，将导出的函数和数据结构引入文档是最有价值的。许多子系统还具有供内部
130使用的kernel-doc注释；除非这些注释放在专门针对相关子系统开发人员的文档中，
131否则不应将其引入文档构建中。
132
133
134修正错字
135~~~~~~~~
136
137
138修复文档中的排版或格式错误是一种快速学习如何创建和发送修补程序的方法，也是
139一项有用的服务。我总是愿意接受这样的补丁。这也意味着，一旦你修复了一些这种
140错误，请考虑转移到更高级的任务，留下一些拼写错误给下一个初学者解决。
141
142请注意，有些并 **不是** 拼写错误，不应该被“修复”：
143
144 - 内核文档中用美式和英式英语拼写皆可，没有必要互相倒换。
145
146 - 在内核文档中，没必要讨论句点后面应该跟一个还是两个空格的问题。其他一些有
147   合理分歧的地方，比如“牛津逗号”，在这也是跑题的。
148
149与对任何项目的任何补丁一样，请考虑您的更改是否真的让事情变得更好。
150
151“上古”文档
152~~~~~~~~~~
153
154一些内核文档是最新的、被维护的，并且非常有用，有些文件确并非如此。尘封、陈旧
155和不准确的文档可能会误导读者，并对我们的整个文档产生怀疑。任何解决这些问题的
156事情都是非常受欢迎的。
157
158无论何时处理文档，请考虑它是否是最新的，是否需要更新，或者是否应该完全删除。
159您可以注意以下几个警告标志：
160
161 - 对2.x内核的引用
162 - 指向SourceForge存储库
163 - 历史记录除了拼写错误啥也没有持续几年
164 - 讨论Git之前时代的工作流
165
166当然，最好的办法是更新文档，添加所需的任何信息。这样的工作通常需要与熟悉相关
167子系统的开发人员合作。当有人善意地询问开发人员，并听取他们的回答然后采取
168行动时，开发人员通常更愿意与这些致力于改进文档的人员合作。
169
170有些文档已经没希望了；例如，我们偶尔会发现引用了很久以前从内核中删除的代码的
171文档。删除过时的文档会碰见令人惊讶的阻力，但我们无论如何都应该这样做。文档中
172多余的粗枝大叶对任何人都没有帮助。
173
174如果一个严重过时的文档中可能有一些有用的信息，而您又无法更新它，那么最好在
175开头添加一个警告。建议使用以下文本::
176
177  .. warning ::
178  	This document is outdated and in need of attention.  Please use
179  	this information with caution, and please consider sending patches
180  	to update it.
181
182这样的话，至少我们长期受苦的读者会得到文件可能会把他们引入歧途的警告。
183
184文档一致性
185~~~~~~~~~~
186
187这里的老前辈们会记得上世纪90年代出现在书架上的Linux书籍，它们只是从网上不同
188位置搜来的文档文件的集合。在此之后，（大部分）这些书都得到了改进，但是内核的
189文档仍然主要是建立在这种模型上。它有数千个文件，几乎每个文件都是与其他文件相
190独立编写的。我们没有一个连贯的内核文档；只有数千个独立的文档。
191
192我们一直试图通过编篡一套“书籍”来改善这种情况，以为特定读者提供成套文档。这
193包括：
194
195 - Documentation/translations/zh_CN/admin-guide/index.rst
196 - Documentation/core-api/index.rst
197 - Documentation/driver-api/index.rst
198 - Documentation/userspace-api/index.rst
199
200以及文档本身这本“书”。
201
202将文档移到适当的书中是一项重要的任务，需要继续进行。不过这项工作还是有一些
203挑战性。移动文档会给处理这些文档的人带来短期的痛苦；他们对这些更改无甚热情
204也是可以理解的。通常情况下，可以将一个文档移动一下；不过我们真的不想一直移动
205它们。
206
207即使所有文件都在正确的位置，我们也只是把一大堆文件变成一群小堆文件。试图将
208所有这些文件组合成一个整体的工作尚未开始。如果你对如何在这方面取得进展有好的
209想法，我们将很高兴了解。
210
211样式表（Stylesheet）改进
212~~~~~~~~~~~~~~~~~~~~~~~~
213
214随着Sphinx的采用，我们得到了比以前更好的HTML输出。但它仍然需要很大的改进；
215Donald Knuth和Edward Tufte可能是映像平平的。这需要调整我们的样式表，以创建
216更具排版效果、可访问性和可读性的输出。
217
218请注意：如果你承担这个任务，你将进入经典的两难领域。即使是相对明显的变化，
219也会有很多意见和讨论。唉，这就是我们生活的世界的本质。
220
221无LaTeX的PDF构建
222~~~~~~~~~~~~~~~~
223
224对于拥有大量时间和Python技能的人来说，这绝对是一项不平凡的任务。Sphinx工具链
225相对较小且包含良好；很容易添加到开发系统中。但是构建PDF或EPUB输出需要安装
226LaTeX，它绝对称不上小或包含良好的。消除Latex将是一件很好的事情。
227
228最初是希望使用 `rst2pdf <https://rst2pdf.org/>`_ 工具来生成PDF，但结果发现
229无法胜任这项任务。不过rst2pdf的开发工作最近似乎又有了起色，这是个充满希望的
230迹象。如果有开发人员愿意与该项目合作，使rst2pdf可与内核文档构建一起工作，
231大家会非常感激。
232
233编写更多文档
234~~~~~~~~~~~~
235
236当然，内核中许多部分的文档严重不足。如果您有编写一个特定内核子系统文档的相应
237知识并愿意这样做，请不要犹豫，编写并向内核贡献结果吧！数不清的内核开发人员和
238用户会感谢你。
239