LWN：如何为Linux内核贡献文档！

关注了就能看到更多这么棒的文章哦～

How to contribute to kernel documentation

By Jonathan Corbet
January 23, 2020

原文来自：https://lwn.net/Articles/810404/

PS. 强烈推荐看一下LWF文章下的评论，笑死，许多人都是原本准备清理文档的，结果文档还没写好，就看不下去别人的那一坨坨代码，给它完全重写了。。。

许多年以前，本人脑子一热没经得住游说，莫名其面就成了kernel documentation maintainer。近来我做了一些演讲，都是关于kernel文档目前状态以及后续如何改善的。其中很重要的一点就是同一些潜在能帮得上忙的开发者交流，希望他们来把一些尚未文档化的内容整理起来。因此我写了本文供review，希望能合入mainline。欢迎读下去来帮助改善kernel文档。

How to help improve kernel documentation

文档在任何软件开发项目中都是非常重要的。好的文档能引来新的开发者，也能帮助现有的开发者能高效工作。如果没有高质量的文档，会需要浪费许多时间来对代码进行反向工程，或者犯一些原本应该可以避免的错误。好的文档可以让项目运转的更加高效，更加可控。

不幸的是，kernel的文档目前目前还远未达到这种体量和重要性的项目中应有的状态。

本文希望能让愿意提供贡献的开发者来共同改进目前的窘境。改善kernel文档的工作需要各种不同技术水平的开发者参与。想要了解kernel开发流程或者希望对社区做贡献的话，文档工作是相对比较容易入手的方向。并且要补完我们的文档的话，已经看到有无数的工作要做，包括许多重要的模块都要覆盖，并且肯定还有遗漏的。如果你想到什么更好的方法来改进文档，也请积极提出。

Addressing warnings

目前编译生成文档的过程中会产生非常多的warning。如果warning太多了，基本就跟一个都没有一样，没人会关注这些warning，甚至在新加的工作里面引入新的warning的时候也都不会注意到这一点。因此在文档相关的to-to list上，最高优先级的事情之一就是消除warning。这个工作本身不难，不过也需要采用正确方式才能最终达成目标。

编译器针对C语言编译时报出的warning许多都是假警报，因此有一些patch的目的就是能让编译器不要再报这个warning。而在documentation build时候的warning则通常都是真正的问题，要想消除这些warning，需要彻底理解这个问题，从根源上解决。因此，修复documentation warning的patch通常不应该拿"fix a warning"作为changelog的标题，而是应该讲明这里修复的问题是什么。

还需要注意的是，documentation warning通常都是来自于C代码里的kerneldoc注释。虽然documentation maintainer很感谢大家发给我们一些修复这类问题的patch，不过documentation tree并不是合入这些patch的正确地方，通常应该把它们发给相应出问题的子系统的maintainer来合入。

举例来说，我从5.5-rc7的documentation build里面随便选了2个warning出来：

    ./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.
   */

这里的问题是缺少了一个"*"，因此我们头脑简单的build系统就没法认出这一块完整的C语言注释了。这个问题，自从在2016年加入这个注释的时候就存在了，已经4年了。加上这个缺失的星号就可以了。然后我看了一下这个文件的修改历史来了解通常修改此文件的patch标题应该怎么写，然后scripts/get_maintainer.pl获取应该把patch发给谁。最终做出来的patch是这样的：

   [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

整个流程只需要几分钟而已，就把这个fix骄傲地发送出去了。当然，后来我发现有人在另一个git tree里面已经fix了这个问题，因此得到了一个重要教训：每次都应该先查一下linux-next来看看是不是有人已经在你之前fix了这个问题。

一般的fix都会需要更多时间，尤其是关于structure的成员、或者函数参数没有文档的。这种情况下就需要搞清楚这些成员或者参数都是用来做什么的，能把它描述清楚。总体来说，这种事情会消耗不少时间，但是非常重要。如果咱们能消除documentation build里面的warning，那么我们可以开始要求开发者们不要在引入新的warning了。

Languishing kerneldoc comments

我们通常都鼓励开发者在代码里面写好kerneldoc注释，不过这些注释中的许多都没有包含在docs build过程中。所以这些信息就比较难获取到，比如，会使得Sphinx无法生成相关的文档链接。因此应该加入kernel-doc directives到文档里，来把这些注释也包含进来，这样就可以让社区的工作不要白费。

可以使用scripts/find-unused-docs.sh工具来找到那些被忽略的注释。

需要注意的是，对那些暴露给外界的（export）的函数和数据结构生成文档能带来最大的价值。许多subsystem里面也对内部函数等来生成了kerneldoc注释，这些不应该加入documentation build里面，除非是把它们专门放到一个专用于帮助此subsystem内部开发者工作的文档中。

Typo fixes

修复拼写错误或者格式错误比较容易，也是一个快速熟悉如何创建patch或者发送patch的方法，并且也对大家都有价值。我非常愿意接收这类patch。不过，建议你在修复了一些之后，就考虑切换到其他一些更有挑战性的任务上去，可以留一些拼写错误问题给今后的新成员们来练手。

不过需要注意下面这些不算是拼写错误，不应该对它进行“fix”：

• 美式拼写和英式拼写在kernel文档里面都是可以接受的。不需要专门做patch来修复这种问题。

• 在kernel文档里面，我们不争论在句号后面是应该放1个还是2个空格。此外，还有一些类似的合理性之争，例如“Oxford comma”等，也都是偏离主题了，我们都不参与这种争议。

无论是对哪个项目提交patch，都请思考一下你的改动是否真的让情况变得更好了。

Ancient documentation

有部分kernel文档是符合现状的，并且持续更新，很有价值的。不过有些文档则不是，它们非常陈旧，其中不准确的信息会误导读者，也会让大家对我们的文档工作产生很坏的印象。因此非常欢迎能对这些领域做些工作。

每次在完善一份文档的时候，请留意它是不是符合现状的，是否需要更新，或者是不是干脆应该把它删除掉。如果一个文档里面充满了过时的信息的话，那么在其中修复一些拼写错误就没多大价值了。你可以格外留意如下这些迹象：

• 引用2.x kernel

• 指向SourceForge仓库或者mailing lists。

• 过去几年里面除了拼写错误修复以外没有什么其他改动。

• 讨论的是采用Git之前的工作流程。

• 内部的changelogs在1997年之后就没有改动。

最好的做法当然是把这些文档更新到最新，补全信息。这样的工作通常需要熟悉这个subsystem的开发者的配合。开发者通常都很乐意帮助那些希望改善文档的人，只要问问题的时候礼貌，并且他们的回复也被认真听取并采纳就行。

有些文档则无法修复了，比如有时候我们会看到一些文档里面描述的代码是kernel很久以前已经删除的代码。令人惊奇的是，移除这些过时文档经常还会碰到很大阻力，不过我们还是需要移除的。文档里面这些额外的过时信息对人们没有好处。

如果，在某个非常过时的文档里面有一些有用的信息，并且你不懂如何更新，那么最好的做法是在文档最前面增加一个警告信息。建议采用如下文字：

    .. warning ::
  	This document is outdated and in need of attention.  Please use
	this information with caution, and please consider sending patches
	to update it.

这样一来，至少读者可以意识到这里要格外注意，避免被误导。

Documentation coherency

LWN的老读者们应该还记得1990年代书店里卖的那些Linux书籍。它们其实都是从网上各个地方搜集起来的各种文档的集合。后来的Linux书籍得到了许多改善，不过kernel的文档目前大多数还是用那种方式写就的。kernel文档包括数千个文件，大多数都是独立写就的，没有跟其他的对照过。也就是说我们没有一套成体系的kernel文档，有的是数千个独立的文档。

我们一直在致力于改善这个情况，通过创建一组“books”来针对特定的读者把文档管理起来。包括www.kernel.org/doc/html下面的user-sace API guide，development-process manual，core API manual，user's and administrator's guide，当然还有documentation manual等等。

因此很重要的一个工作就是把各个文档移动到合适的book里面，需要不断推进这个工作。不过这里有一些挑战。因为移动文档文件会对那些需要用到这个文档的开发者们产生一些阵痛，他们肯定不会很赞成这个工作。做这些会方便读者而不是方便作者的整理工作，通常都会有一些阻力。也许可以先一次只移动一个文件，不过我们实在不想不断轮着来一遍。

哪怕所有文档都在正确的位置了，我们也只是把一大堆文档分散成了许多小堆。还是需要把这些文档串联吗起来形成一个统一的文档，这个工作尚未开始。如果读者关于这个方向有什么好主意，非常欢迎反馈出来。

Stylesheet improvements

采用Sphinx之后，我们可以生成比以前更加好看的HTML文档了。不过还是有许多可以改进的地方。Donald Knuth和Edward Tufte肯定很不以为然。这需要修改我们的stylesheet（样式表）来创建出一些适合印刷的、容易访问的、以及更方便阅读的输出格式。

注意：如果你接下了这个任务，那么你就会踏入一个传统固有领域。你会收到许多意见，也会看到很多讨论，哪怕你只是做了一些很显而易见的改动。我们生活的这个世界就是这样的。

Non-LaTex PDF build

这肯定是一个工作量很大的任务，相应的开发者需要有许多时间，也要熟练掌握Python。Sphinx toolchain本身不算大，对外依赖也不多，很容易加到一个开发系统里面去。不过编译生成PDF或者EPUB则需要安装LaTex，它可一点都不小，也需要许多依赖。最好能够避免使用LaTex。

原先我们希望使用rst2pdf tool来生成PDF，不过后来进展不好。近来似乎rst2pdf的开发工作又开始活跃起来了，这是个好消息。如果有一个合适的开发者能和rst2pdf项目合作，把它跟kernel documentation build结合起来，那么我们大家都会永远感谢他的。

Write more documentation

当然，kernel里面还有许多地方文档还很缺乏。如果你对某个kernel subsystem比较了解，可以并且也愿意撰写文档，那么请不要犹豫，写些东西出来为kernel做贡献吧。无数的kernel开发者和用户都会感谢你。

PS：也许有些人很想看一下我的那些演讲，可以看这里Kernel Recipes 2019的：https://www.youtube.com/watch?v=1LuAIUKqKDk

全文完

LWN文章遵循CC BY-SA 4.0许可协议。

欢迎分享、转载及基于现有协议再创作～

长按下面二维码关注，关注LWN深度文章以及开源社区的各种新近言论～