diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2021-04-26 23:22:43 +0300 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2021-04-26 23:22:43 +0300 |
commit | 2f9ef0559efbee18a10a3ca26eefe57f69918693 (patch) | |
tree | 3c30d105078c06b51de764e703a59f6ae1c2bb5a /Documentation/translations/zh_CN/doc-guide/parse-headers.rst | |
parent | 0c855563182001c829065faa17f8e29e9ceffe13 (diff) | |
parent | 441ca977a84dadac6173db7c07c25db110b76c1e (diff) | |
download | linux-2f9ef0559efbee18a10a3ca26eefe57f69918693.tar.xz |
Merge tag 'docs-5.13' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"It's been a relatively busy cycle in docsland, though more than
usually well contained to Documentation/ itself. Highlights include:
- The Chinese translators have been busy and show no signs of
stopping anytime soon. Italian has also caught up.
- Aditya Srivastava has been working on improvements to the
kernel-doc script.
- Thorsten continues his work on reporting-issues.rst and related
documentation around regression reporting.
- Lots of documentation updates, typo fixes, etc. as usual"
* tag 'docs-5.13' of git://git.lwn.net/linux: (139 commits)
docs/zh_CN: add openrisc translation to zh_CN index
docs/zh_CN: add openrisc index.rst translation
docs/zh_CN: add openrisc todo.rst translation
docs/zh_CN: add openrisc openrisc_port.rst translation
docs/zh_CN: add core api translation to zh_CN index
docs/zh_CN: add core-api index.rst translation
docs/zh_CN: add core-api irq index.rst translation
docs/zh_CN: add core-api irq irqflags-tracing.rst translation
docs/zh_CN: add core-api irq irq-domain.rst translation
docs/zh_CN: add core-api irq irq-affinity.rst translation
docs/zh_CN: add core-api irq concepts.rst translation
docs: sphinx-pre-install: don't barf on beta Sphinx releases
scripts: kernel-doc: improve parsing for kernel-doc comments syntax
docs/zh_CN: two minor fixes in zh_CN/doc-guide/
Documentation: dev-tools: Add Testing Overview
docs/zh_CN: add translations in zh_CN/dev-tools/gcov
docs: reporting-issues: make people CC the regressions list
MAINTAINERS: add regressions mailing list
doc:it_IT: align Italian documentation
docs/zh_CN: sync reporting-issues.rst
...
Diffstat (limited to 'Documentation/translations/zh_CN/doc-guide/parse-headers.rst')
-rw-r--r-- | Documentation/translations/zh_CN/doc-guide/parse-headers.rst | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst new file mode 100644 index 000000000000..a08819e904ed --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst @@ -0,0 +1,187 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/parse-headers.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +===================== +包含用户空间API头文件 +===================== + +有时,为了描述用户空间API并在代码和文档之间生成交叉引用,需要包含头文件和示例 +C代码。为用户空间API文件添加交叉引用还有一个好处:如果在文档中找不到相应符号, +Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。 +:ref:`parse_headers.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。 +在构建文档时,必须通过Makefile调用它。有关如何在内核树中使用它的示例,请参阅 +``Documentation/userspace-api/media/Makefile`` 。 + +.. _parse_headers_zh: + +parse_headers.pl +---------------- + +脚本名称 +~~~~~~~~ + + +parse_headers.pl——解析一个C文件,识别函数、结构体、枚举、定义并对Sphinx文档 +创建交叉引用。 + + +用法概要 +~~~~~~~~ + + +\ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>] + +<选项> 可以是: --debug, --help 或 --usage 。 + + +选项 +~~~~ + + + +\ **--debug**\ + + 开启脚本详细模式,在调试时很有用。 + + +\ **--usage**\ + + 打印简短的帮助信息并退出。 + + + +\ **--help**\ + + 打印更详细的帮助信息并退出。 + + +说明 +~~~~ + +通过C头文件或源文件(<C文件>)中为描述API的文档编写的带交叉引用的 ..预格式化 +文本 块将文件转换成重构文本(RST)。它接受一个可选的<例外文件>,其中描述了 +哪些元素将被忽略或指向非默认引用。 + +输出被写入到<输出文件>。 + +它能够识别定义、函数、结构体、typedef、枚举和枚举符号,并为它们创建交叉引用。 +它还能够区分用于指定Linux ioctl的 ``#define`` 。 + +<例外文件> 包含两种类型的语句: \ **ignore**\ 或 \ **replace**\ . + +ignore标记的语法为: + + +ignore \ **type**\ \ **name**\ + +The \ **ignore**\ 意味着它不会为类型为 \ **type**\ 的 \ **name**\ 符号生成 +交叉引用。 + + +replace标记的语法为: + + +replace \ **type**\ \ **name**\ \ **new_value**\ + +The \ **replace**\ 味着它将为 \ **type**\ 类型的 \ **name**\ 符号生成交叉引 +用,但是它将使用 \ **new_value**\ 来取代默认的替换规则。 + + +这两种语句中, \ **type**\ 可以是以下任一项: + + +\ **ioctl**\ + + ignore 或 replace 语句应用于ioctl定义,如: + + #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) + + + +\ **define**\ + + ignore 或 replace 语句应用于在<C文件>中找到的任何其他 ``#define`` 。 + + + +\ **typedef**\ + + ignore 和 replace 语句应用于<C文件>中的typedef语句。 + + + +\ **struct**\ + + ignore 和 replace 语句应用于<C文件>中的结构体名称语句。 + + + +\ **enum**\ + + ignore 和 replace 语句应用于<C文件>中的枚举名称语句。 + + + +\ **symbol**\ + + ignore 和 replace 语句应用于<C文件>中的枚举值名称语句。 + + replace语句中, \ **new_value**\ 会自动使用 \ **typedef**\ , \ **enum**\ + 和 \ **struct**\ 类型的 :c:type: 引用;以及 \ **ioctl**\ , \ **define**\ 和 + \ **symbol**\ 类型的 :ref: 。引用的类型也可以在replace语句中显式定义。 + + +示例 +~~~~ + + +ignore define _VIDEODEV2_H + + +忽略<C文件>中的 #define _VIDEODEV2_H 。 + +ignore symbol PRIVATE + + +如下结构体: + +enum foo { BAR1, BAR2, PRIVATE }; + +不会为 \ **PRIVATE**\ 生成交叉引用。 + +replace symbol BAR1 :c:type:\`foo\` +replace symbol BAR2 :c:type:\`foo\` + + +如下结构体: + +enum foo { BAR1, BAR2, PRIVATE }; + +它会让BAR1和BAR2枚举符号交叉引用C域中的foo符号。 + + + +缺陷 +~~~~ + + +请向Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。 + +中文翻译问题请找中文翻译维护者。 + + +版权 +~~~~ + + +版权所有 (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> + +许可证 GPLv2:GNU GPL version 2 <https://gnu.org/licenses/gpl.html> + +这是自由软件:你可以自由地修改和重新发布它。 +在法律允许的范围内,**不提供任何保证**。 |