Add new translation Documentation/translations/zh_CN/doc-guide/kernel-doc.rst Signed-off-by: Wu XiangCheng <bobwxc@xxxxxxxx> Reviewed-by: Yanteng Si <siyanteng@xxxxxxxxxxx> --- .../zh_CN/doc-guide/kernel-doc.rst | 500 ++++++++++++++++++ 1 file changed, 500 insertions(+) create mode 100644 Documentation/translations/zh_CN/doc-guide/kernel-doc.rst diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst new file mode 100644 index 000000000000..b0427944f8f0 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst @@ -0,0 +1,500 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/kernel-doc.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@xxxxxxxx> + +编写kernel-doc注释 +================== + +Linux内核源文件可以包含kernel-doc格式的结构化文档注释，用以描述代码的函数、 +类型和设计。将文档嵌入源文件更容易保持文档最新。 + +.. note:: 内核文档格式与javadoc、gtk-doc或Doxygen看似很相似，但由于历史原因， + 实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循 + 此处描述的风格。 + +.. note:: kernel-doc无法包含Rust代码：请参考 + :ref:`Documentation/rust/docs.rst <rust_docs>`。 + +从注释中提取kernel-doc结构，并从中生成适当的 `Sphinx C 域`_ 函数和带有锚点的 +类型描述。这些注释将被过滤以生成特殊kernel-doc高亮和交叉引用。详见下文。 + +.. _Sphinx C 域: http://www.sphinx-doc.org/en/stable/domains.html + +使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出到可加载模块的每个函数都 +应该有一个kernel-doc注释。模块使用的头文件中的函数和数据结构也应该有 +kernel-doc注释。 + +对于其他内核文件（未标记为 ``static`` ）中外部可见的函数，提供kernel-doc格式 +的文档是一个很好的实践。我们也建议为私有（文件 ``static`` ）程序提供kernel-doc +格式的文档，以确保内核源代码布局的一致性。此建议优先级较低，由内核源文件的 +维护者自行决定。 + +如何格式化kernel-doc注释 +------------------------ + +kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取以这种方式 +标记的注释。注释其余部分的格式类似于一个普通的多行注释，左侧有一列星号，以 +``*/`` 行结束。 + +函数和类型的kernel-doc注释应该放在所描述的函数或类型之前，以便最大限度地提高 +更改代码的人同时更改文档的可能性。概述kernel-doc注释可以放在最顶部的任何地方。 + +用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式 +是否正确。例如:: + + scripts/kernel-doc -v -none drivers/foo/bar.c + +当请求执行额外的gcc检查时，内核构建将验证文档格式:: + + make W=n + +函数文档 +-------- + +函数和函数式宏的kernel-doc注释的一般格式是:: + + /** + * 函数名() - 函数简要说明. + * @参数1: 描述第一个参数. + * @参数2: 描述第二个参数. + * 可以为参数提供一段 + * 多行描述. + * + * 更详细的描述，进一步讨论函数 函数名(), 这可能对使用或修改它的人有用. + * 以空注释行开始, 内部可以包含空注释行. + * + * 详细描述可以有多个段落. + * + * Context: 描述函数是否可以休眠, 它需要、释放或期望持有什么锁. + * 可以写多行. + * Return: 描述函数返回值. + * + * 返回值描述也可以有多个段落, + * 并且应该放在注释块的末尾. + */ + +函数名后面的简短描述可以跨多行，并以参数描述、空注释行或注释块结尾结束。 + +函数参数 +~~~~~~~~ + +每个函数参数都应该按照顺序描述，紧跟在函数简要说明之后。不要在函数描述和参数 +之间，也不要在参数之间留空。 + +每个 ``@参数:`` 描述可以跨多行。 + +.. note:: + + 如果 ``@参数`` 描述有多行，则说明的续行应该从上一行的同一列开始:: + + * @参数: 较长说明 + * 的续行 + + 或:: + + * @参数: + * 较长说明 + * 的续行 + +如果函数的参数数目可变，则需用kernel-doc格式对其进行描述:: + + * @...: 描述 + +函数上下文 +~~~~~~~~~~ + +可调用函数的上下文应该在 ``Context`` 节中描述。此节应该包括函数是休眠的还是 +可以从中断上下文调用的，以及它需要什么锁、释放什么锁和期望它的调用者持有什么 +锁。 + +例如:: + + * Context: Any context. + * Context: Any context. Takes and releases the RCU lock. + * Context: Any context. Expects <lock> to be held by caller. + * Context: Process context. May sleep if @gfp flags permit. + * Context: Process context. Takes and releases <mutex>. + * Context: Softirq or process context. Takes and releases <lock>, BH-safe. + * Context: Interrupt context. + +返回值 +~~~~~~ + +如有返回值，应在 ``Return`` 节中描述。 + +.. note:: + + #) 您提供的多行描述文本 *不会* 识别换行符，因此如果您想将某些文本预格式化， + 如:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + 它们在最终文档中变成一行:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + 因此，为了在需要的地方换行，您需要使用ReST列表，例如:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) 如果您提供的描述性文本中的行以某个后跟冒号的短语开头，则每一个这种短语 + 都将被视为新的节标题，可能会产生意料不到的效果。 + +结构体、共用体、枚举类型文档 +---------------------------- + +结构体（struct）、共用体（union）、枚举（enum）类型kernel-doc注释的一般格式为:: + + /** + * struct 结构体名 - 简要描述. + * @成员1: 成员1描述. + * @成员2: 成员2描述. + * 可以为成员提供 + * 多行描述. + * + * 结构体的描述. + */ + +可以用 ``union`` 或 ``enum`` 替换上面示例中的 ``struct`` ，以描述共用体或枚举。 +``成员`` 用于表示枚举中的元素或共用体成员。 + +结构体名称后面的简要说明可以跨多行，并以成员说明、空白注释行或注释块结尾结束。 + +成员 +~~~~ + +结构体、共用体和枚举的成员应以与函数参数相同的方式记录；它们后紧跟简短的描述， +并且为多行。 + +在结构体或共用体描述中，可以使用 ``private:`` 和 ``public:`` 注释标签。 +``private:`` 域内的字段不会列在生成的文档中。 + +``private:`` 和 ``public:`` 标签必须紧跟在 ``/*`` 注释标记之后。可以选择是否 +在 ``:`` 和 ``*/`` 结束标记之间包含注释。 + +例子:: + + /** + * struct 张三 - 简短描述 + * @a: 第一个成员 + * @b: 第二个成员 + * @d: 第三个成员 + * + * 详细描述 + */ + struct 张三 { + int a; + int b; + /* private: 仅内部使用 */ + int c; + /* public: 下一个是公有的 */ + int d; + }; + +嵌套的结构体/共用体 +~~~~~~~~~~~~~~~~~~~ + +嵌套的结构体/共用体可像这样记录:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @memb1: first member of anonymous union/anonymous struct + * @memb2: second member of anonymous union/anonymous struct + * @memb3: third member of anonymous union/anonymous struct + * @memb4: fourth member of anonymous union/anonymous struct + * @bar: non-anonymous union + * @bar.st1: struct st1 inside @bar + * @bar.st2: struct st2 inside @bar + * @bar.st1.memb1: first member of struct st1 on union bar + * @bar.st1.memb2: second member of struct st1 on union bar + * @bar.st2.memb1: first member of struct st2 on union bar + * @bar.st2.memb2: second member of struct st2 on union bar + */ + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int memb1; + int memb2; + }; + struct { + void *memb3; + int memb4; + }; + }; + union { + struct { + int memb1; + int memb2; + } st1; + struct { + void *memb1; + int memb2; + } st2; + } bar; + }; + +.. note:: + + #) 在记录嵌套结构体或共用体时，如果结构体/共用体 ``张三`` 已命名，则其中 + 的成员 ``李四`` 应记录为 ``@张三.李四:`` + + #) 当嵌套结构体/共用体是匿名的时，其中的成员 ``李四`` 应记录为 ``@李四:`` + +行间注释文档 +~~~~~~~~~~~~ + +结构成员也可在定义时以行间注释形式记录。有两种样式，一种是单行注释，其中开始 +``/**`` 和结束 ``*/`` 位于同一行；另一种是多行注释，开头结尾各自位于一行，就 +像所有其他核心文档注释一样:: + + /** + * struct 张三 - 简短描述. + * @张三: 成员张三. + */ + struct 张三 { + int 张三; + /** + * @李四: 成员李四. + */ + int 李四; + /** + * @王五: 成员王五. + * + * 此处，成员描述可以为好几段. + */ + int 王五; + union { + /** @儿子: 单行描述. */ + int 儿子; + }; + /** @赵六: 描述@张三里面的结构体@赵六 */ + struct { + /** + * @赵六.女儿: 描述@张三.赵六里面的@女儿 + */ + int 女儿; + } 赵六; + }; + +Typedef文档 +----------- + +Typedef的kernel-doc文档注释的一般格式为:: + + /** + * typedef 类型名称 - 简短描述. + * + * 类型描述. + */ + +还可以记录带有函数原型的typedef:: + + /** + * typedef 类型名称 - 简短描述. + * @参数1: 参数1的描述 + * @参数2: 参数2的描述 + * + * 类型描述. + * + * Context: 锁（Locking）上下文. + * Return: 返回值的意义. + */ + typedef void (*类型名称)(struct v4l2_ctrl *参数1, void *参数2); + +高亮与交叉引用 +-------------- + +在kernel-doc注释的描述文本中可以识别以下特殊模式，并将其转换为正确的 +reStructuredText标记和 `Sphinx C 域`_ 引用。 + +.. attention:: 以下内容 **仅** 在kernel-doc注释中识别， **不会** 在普通的 + reStructuredText文档中识别。 + +``funcname()`` + 函数引用。 + +``@parameter`` + 函数参数的名称（未交叉引用，仅格式化）。 + +``%CONST`` + 常量的名称（未交叉引用，仅格式化）。 + +````literal```` + 预格式化文本块。输出将使用等距字体。 + + 若你需要使用在kernel-doc脚本或reStructuredText中有特殊含义的字符，则此功能 + 非常有用。 + + 若你需要在函数描述中使用类似于 ``%ph`` 的东西，这特别有用。 + +``$ENVVAR`` + 环境变量名称（未交叉引用，仅格式化）。 + +``&struct name`` + 结构体引用。 + +``&enum name`` + 枚举引用。 + +``&typedef name`` + Typedef引用。 + +``&struct_name->member`` or ``&struct_name.member`` + 结构体或共用体成员引用。交叉引用将链接到结构体或共用体定义，而不是直接到成员。 + +``&name`` + 泛类型引用。请首选上面描述的完整引用方式。此法主要是为了可能未描述的注释。 + +从reStructuredText交叉引用 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +无需额外的语法来从reStructuredText文档交叉引用kernel-do注释中定义的函数和类型。 +只需以 ``()`` 结束函数名，并在类型之前写上 ``struct`` ， ``union`` ， ``enum`` +或 ``typedef`` 。 +例如:: + + See foo(). + See struct foo. + See union bar. + See enum baz. + See typedef meh. + +若要在交叉引用链接中使用自定义文本，可以通过以下语法进行:: + + See :c:func:`my custom link text for function foo <foo>`. + See :c:type:`my custom link text for struct bar <bar>`. + +有关更多详细信息，请参阅 `Sphinx C 域`_ 文档。 + +总述性文档注释 +-------------- + +为了促进源代码和注释紧密联合，可以将kernel-doc文档块作为自由形式的注释，而 +不是函数、结构、联合、枚举或typedef的绑定kernel-doc。例如，这可以用于解释 +驱动程序或库代码的操作理论。 + +这是通过使用带有节标题的 ``DOC:`` 节关键字来实现的。 + +总述或高层级文档注释的一般格式为:: + + /** + * DOC: Theory of Operation + * + * The whizbang foobar is a dilly of a gizmo. It can do whatever you + * want it to do, at any time. It reads your mind. Here's how it works. + * + * foo bar splat + * + * The only drawback to this gizmo is that is can sometimes damage + * hardware, software, or its subject(s). + */ + +``DOC:`` 后面的标题用作源文件中的标题，但也用作提取文档注释的标识符。因此， +文件中的标题必须是唯一的。 + +包含kernel-doc注释 +================== + +文档注释可以被包含在任何使用专用kernel-doc Sphinx指令扩展的reStructuredText +文档中。 + +kernel-doc指令的格式如下:: + + .. kernel-doc:: source + :option: + +*source* 是相对于内核源代码树的源文件路径。 +支持以下指令选项： + +export: *[source-pattern ...]* + 包括 *source* 中使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的所有 + 函数的文档，无论是在 *source* 中还是在 *source-pattern* 指定的任何文件中。 + + 当kernel-doc注释被放置在头文件中，而 ``EXPORT_SYMBOL`` 和 ``EXPORT_SYMBOL_GPL`` + 位于函数定义旁边时， *source-pattern* 非常有用。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :export: + + .. kernel-doc:: include/net/mac80211.h + :export: net/mac80211/*.c + +internal: *[source-pattern ...]* + 包括 *source* 中所有在 *source* 或 *source-pattern* 的任何文件中都没有使用 + ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的函数和类型的文档。 + + 例子:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :internal: + +identifiers: *[ function/type ...]* + 在 *source* 中包含每个 *function* 和 *type* 的文档。如果没有指定 *function* ， + 则 *source* 中所有函数和类型的文档都将包含在内。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :identifiers: bitmap_parselist bitmap_parselist_user + + .. kernel-doc:: lib/idr.c + :identifiers: + +no-identifiers: *[ function/type ...]* + 排除 *source* 中所有 *function* 和 *type* 的文档。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :no-identifiers: bitmap_parselist + +functions: *[ function/type ...]* + 这是“identifiers”指令的别名，已弃用。 + +doc: *title* + 包含 *source* 中由 *title* 标题标识的 ``DOC:`` 文档段落。 *title* 中允许 + 空格；不要在 *title* 上加引号。 *title* 仅用作段落的标识符，不包含在输出中。 + 请确保在所附的reStructuredText文档中有适当的标题。 + + 例子:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :doc: High Definition Audio over HDMI and Display Port + +如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。 + +kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。 +在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。 + +.. _kernel_doc_zh: + +如何使用kernel-doc生成手册（man）页 +----------------------------------- + +如果您只想使用kernel-doc生成手册页，可以从内核git树这样做:: + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- :^Documentation :^tools) \ + | scripts/split-man.pl /tmp/man + +一些旧版本的git不支持路径排除语法的某些变体。 +以下命令之一可能适用于这些版本:: + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ + | scripts/split-man.pl /tmp/man + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ + | scripts/split-man.pl /tmp/man + -- 2.20.1
