如何帮助改进内核文档¶
文档是任何软件开发项目的重要组成部分。良好的文档有助于引入新的开发者，并帮助已有的开发者更有效地工作。如果没有高质量的文档，大量时间将被浪费在逆向工程代码和避免可避免的错误上。
不幸的是，内核的文档目前远远达不到支持如此规模和重要性的项目所需的要求。
本指南适用于希望改善这种状况的贡献者。内核文档的改进可以由各种技能水平的开发人员完成；这是总体上学习内核流程并在社区中找到一席之地的相对简单的方法。以下内容的大部分是文档维护人员最迫切需要完成的任务列表。
文档 TODO 列表¶
为了使我们的文档达到应有的水平，需要执行的任务清单是无穷无尽的。此列表包含许多重要项目，但远非详尽无遗；如果您看到改进文档的不同方法，请不要犹豫！
解决警告¶
文档构建目前会发出令人难以置信的警告数量。当您有那么多警告时，您可能没有任何警告；人们会忽略它们，并且永远不会注意到他们的工作何时添加了新的警告。因此，消除警告是文档 TODO 列表中优先级最高的任务之一。任务本身相当简单，但必须以正确的方式进行才能成功。
编译器为 C 代码发出的警告通常可以被视为误报，导致补丁旨在简单地让编译器闭嘴。来自文档构建的警告几乎总是指向一个实际问题；消除这些警告需要理解问题并在其源头解决它。因此，修复文档警告的补丁可能不应在变更日志标题中说“修复警告”；它们应该指出已修复的实际问题。
另一个重要的一点是，文档警告通常是由 C 代码中 kerneldoc 注释中的问题引起的。虽然文档维护者感谢被复制到这些警告的修复程序，但文档树通常不是实际执行这些修复程序的正确树；它们应该发送给相关子系统的维护者。
例如，在文档构建中，我几乎随机抓取了一对警告
./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()
（为了便于阅读，这些行被拆分了）。
快速查看上面命名的源文件，发现了一些如下所示的 kerneldoc 注释
/**
* 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.
*/
问题是缺少“*”，这混淆了构建系统对 C 注释块外观的简单想法。自从 2016 年添加该注释以来，这个问题一直存在 —— 整整四年。修复它只需要添加缺少的星号。快速查看该文件的历史记录，显示了主题行的正常格式，并且 scripts/get_maintainer.pl 告诉我应该收到它的人（将补丁的路径作为参数传递给 scripts/get_maintainer.pl）。生成的补丁如下所示
[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
整个过程只花了几个分钟。当然，然后我发现其他人已经在单独的树中修复了它，突出了另一个教训：在您深入研究之前，始终检查 linux-next 以查看问题是否已修复。
其他修复将花费更长的时间，特别是那些与缺少文档的结构成员或函数参数相关的修复。在这种情况下，有必要确定这些成员或参数的作用，并正确描述它们。总的来说，这项任务有时会有点乏味，但它非常重要。如果我们可以真正消除文档构建中的警告，那么我们可以开始期望开发人员避免添加新的警告。
除了来自常规文档构建的警告之外，您还可以运行 make refcheckdocs 以查找对不存在的文档文件的引用。
逐渐消失的 kerneldoc 注释¶
鼓励开发人员为他们的代码编写 kerneldoc 注释，但许多这些注释永远不会被拉入文档构建中。这使得这些信息更难找到，并且，例如，使得 Sphinx 无法生成指向该文档的链接。向文档添加 kernel-doc 指令以引入这些注释可以帮助社区获得创建它们所投入的全部价值。
可以使用 scripts/find-unused-docs.sh 工具来查找这些被忽略的注释。
请注意，最有价值的是引入导出函数和数据结构的文档。许多子系统也有供内部使用的 kerneldoc 注释；除非它们放置在专门针对在相关子系统内工作的开发人员的文档中，否则不应将这些注释拉入文档构建中。
错别字修复¶
修复文档中的排版或格式错误是弄清楚如何创建和发送补丁的一种快速方法，并且这是一项有用的服务。我总是愿意接受这样的补丁。也就是说，一旦您修复了一些，请考虑继续执行更高级的任务，为下一个初学者留下一些错别字。
请注意，有些东西不是错别字，不应该被“修复”
内核文档中允许使用美式英语和英式英语拼写。没有必要通过将其替换为另一个来修复一个。
句点后是否应跟一个或两个空格的问题不应在内核文档的上下文中进行讨论。其他存在合理分歧的领域，例如“牛津逗号”，在这里也不相关。
与对任何项目的任何补丁一样，请考虑您的更改是否真的使事情变得更好。
古老的文档¶
一些内核文档是最新的、经过维护的，并且是有用的。一些文档 ... 不是。尘封的、陈旧的和不准确的文档会误导读者，并使人们怀疑我们的文档的整体性。任何可以解决此类问题的事情都非常受欢迎。
每当您处理文档时，请考虑它是否是最新的，是否需要更新，或者是否应该完全删除。您可以注意以下一些警告信号
引用 2.x 内核
指向 SourceForge 存储库的指针
多年来历史上只有错别字修复
对 Git 之前的工作流程的讨论
当然，最好的办法是使文档保持最新，添加所需的任何信息。当然，这种工作通常需要熟悉相关子系统的开发人员的合作。当开发人员被友好地询问，并且他们的答案被倾听并付诸行动时，他们通常非常愿意与致力于改进文档的人员合作。
一些文档已经没有希望了；例如，我们偶尔会发现引用很久以前从内核中删除的代码的文档。对删除过时文档存在令人惊讶的抵制，但我们仍然应该这样做。我们的文档中的额外垃圾对任何人都没有帮助。
如果在严重过时的文档中可能有一些有用的信息，并且您无法更新它，那么最好的办法可能是在开头添加一个警告。建议使用以下文字
.. warning ::
This document is outdated and in need of attention. Please use
this information with caution, and please consider sending patches
to update it.
这样，至少我们长期受苦的读者已被警告该文档可能会误导他们。
文档一致性¶
这里的老前辈会记得 20 世纪 90 年代出现在书架上的 Linux 书籍。它们只是从网上各个位置收集的文档文件的集合。自那时以来，书籍（大部分）有所改进，但内核的文档仍然主要建立在该模型之上。它由数千个文件组成，几乎每个文件都是与其他文件隔离编写的。我们没有连贯的内核文档，我们有数千个单独的文档。
我们一直在尝试通过创建一组为特定读者分组文档的“书籍”来改善这种情况。这些包括
以及这本关于文档本身的指南。
将文档移动到适当的书籍中是一项重要的任务，需要继续进行。但是，这项工作存在一些挑战。移动文档文件会给使用这些文件的人带来短期痛苦；他们对这种变化可以理解地不热情。通常可以提出一次移动文档的理由；但是，我们真的不想继续移动它们。
即使所有文档都放在正确的位置，我们也只是设法将一大堆变成一组较小的堆。尝试将所有这些文档整合到一个整体中的工作尚未开始。如果您对我们如何在这方面取得进展有好的想法，我们将非常乐意听到它们。
样式表改进¶
通过采用 Sphinx，我们获得了比以往更好的 HTML 输出。但是它仍然可以使用很多改进；Donald Knuth 和 Edward Tufte 会留下深刻印象。这需要调整我们的样式表，以创建更多排版上合理的、可访问的且可读的输出。
请注意：如果您承担这项任务，您将进入经典的自行车棚领域。即使对于相对明显的更改，也希望有很多意见和讨论。唉，这就是我们生活的世界的本质。
非 LaTeX PDF 构建¶
对于有大量时间和 Python 技能的人来说，这是一项非常重要的任务。Sphinx 工具链相对较小且包含良好；很容易添加到开发系统中。但是构建 PDF 或 EPUB 输出需要安装 LaTeX，它绝不是小型或包含良好的。消除它将是一件好事。
最初的希望是使用 rst2pdf 工具 (https://rst2pdf.org/) 进行 PDF 生成，但事实证明它无法胜任这项任务。最近，rst2pdf 的开发工作似乎再次活跃起来，这是一个充满希望的迹象。如果一位积极性足够的开发人员与该项目合作，使 rst2pdf 与内核文档构建一起工作，那么世界将永远感激不尽。
编写更多文档¶
当然，内核的绝大部分都严重缺乏文档。如果您有记录特定内核子系统的知识和这样做的愿望，请不要犹豫，进行一些编写并将结果贡献给内核。无数的内核开发人员和用户会感谢您。