Documentation/translations/zh_CN/doc-guide/contributing.rst

Source file repositories/reference/linux-study-clean/Documentation/translations/zh_CN/doc-guide/contributing.rst

File Facts

System
Linux kernel
Corpus path
Documentation/translations/zh_CN/doc-guide/contributing.rst
Extension
.rst
Size
11729 bytes
Lines
239
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: exported/initcall integration point
Status
integration implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

.. include:: ../disclaimer-zh_CN.rst

:Original: Documentation/doc-guide/contributing.rst

:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>

如何帮助改进内核文档
====================

在任何软件开发项目中，文档都是重要组成部分。好的文档有助于引入新的开发人员，
并帮助已有的开发人员更有效地工作。如果缺少高质量的文档，大量的时间就会浪费在
代码的逆向工程和犯本可避免的错误上。

不幸的是，内核的文档目前远远不能满足支持如此规模和重要性的项目的需要。

本指南适用于希望帮助改善这种状况的贡献者。内核文档的改进可以由开发者在不同的
技能层级上进行；这也是一条相对简单可以帮助您了解内核过程并在社区中找到一席之
地的路径。下面的大部分内容是文档维护人员列出的最迫切需要完成的任务。

文档待办事项列表
----------------

为了使我们的文档达到应有的水平，需要完成的任务数不胜数。此列表包含许多重要的
项目，但还远远不够详尽；如果您知道改进文档的其他方法，请不要羞于启齿。

消除警告（WARNING）
~~~~~~~~~~~~~~~~~~~

文档构建目前出现了数量惊人的警告。虱子多了不痒，债多了不愁；大伙儿忽略了它们，
他们永远不会注意到他们的工作增加了新的警告。因此，消除警告是文档待办事项列表
中优先级最高的任务之一。这项任务本身相当简单，但必须以正确的方式进行，才能取
得成功。

C代码编译器发出的警告常常会被视为误报，从而导致出现了旨在让编译器闭嘴的补丁。
文档构建中的警告几乎总是指向真正的问题；要消除这些警告，需要理解问题并从源头上
解决问题。因此，修复文档警告的补丁不应在标题中直接写“修复警告”；它们应该指明
真正修复的问题。

另一个重点是，文档警告常常由C代码里kernel-doc注释中的问题引起。虽然文档维护
人员对收到这些修复补丁的副本表示感谢，但是文档树实际上通常并不适合接受这些
补丁；它们应该被交给相关子系统的维护人员。

例如，在一次文档构建中，我几乎是随意选取了一对警告::

  ./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()

（作了断行以便于阅读）

简单看一下上面给出的源文件，会发现几个kernel-doc注释，如下所示::

  /**
   * 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``
来搞清谁应当收到此补丁。生成的补丁如下所示::

  [PATCH] PM / devfreq: Fix two malformed kerneldoc comments

Annotation

Implementation Notes