zh_CN/doc-guide/parse-headers.rst

0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 .. include:: ../disclaimer-zh_CN.rst
0004
0005 :Original: Documentation/doc-guide/parse-headers.rst
0006
0007 :译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>
0008
0009 =====================
0010 包含用户空间API头文件
0011 =====================
0012
0013 有时，为了描述用户空间API并在代码和文档之间生成交叉引用，需要包含头文件和示例
0014 C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号，
0015 Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。
0016 :ref:`parse_headers.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。
0017 在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅
0018 ``Documentation/userspace-api/media/Makefile`` 。
0019
0020 .. _parse_headers_zh:
0021
0022 parse_headers.pl
0023 ----------------
0024
0025 脚本名称
0026 ~~~~~~~~
0027
0028
0029 parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档
0030 创建交叉引用。
0031
0032
0033 用法概要
0034 ~~~~~~~~
0035
0036
0037 \ **parse_headers.pl**\  [<选项>] <C文件> <输出文件> [<例外文件>]
0038
0039 <选项> 可以是： --debug, --help 或 --usage 。
0040
0041
0042 选项
0043 ~~~~
0044
0045
0046
0047 \ **--debug**\
0048
0049  开启脚本详细模式，在调试时很有用。
0050
0051
0052 \ **--usage**\
0053
0054  打印简短的帮助信息并退出。
0055
0056
0057
0058 \ **--help**\
0059
0060  打印更详细的帮助信息并退出。
0061
0062
0063 说明
0064 ~~~~
0065
0066 通过C头文件或源文件（<C文件>）中为描述API的文档编写的带交叉引用的 ..预格式化
0067 文本 块将文件转换成重构文本（RST）。它接受一个可选的<例外文件>，其中描述了
0068 哪些元素将被忽略或指向非默认引用。
0069
0070 输出被写入到<输出文件>。
0071
0072 它能够识别定义、函数、结构体、typedef、枚举和枚举符号，并为它们创建交叉引用。
0073 它还能够区分用于指定Linux ioctl的 ``#define`` 。
0074
0075 <例外文件> 包含两种类型的语句： \ **ignore**\  或 \ **replace**\ .
0076
0077 ignore标记的语法为：
0078
0079
0080 ignore \ **type**\  \ **name**\
0081
0082 The \ **ignore**\  意味着它不会为类型为 \ **type**\ 的 \ **name**\ 符号生成
0083 交叉引用。
0084
0085
0086 replace标记的语法为：
0087
0088
0089 replace \ **type**\  \ **name**\  \ **new_value**\
0090
0091 The \ **replace**\  味着它将为 \ **type**\ 类型的 \ **name**\ 符号生成交叉引
0092 用，但是它将使用 \ **new_value**\ 来取代默认的替换规则。
0093
0094
0095 这两种语句中， \ **type**\ 可以是以下任一项：
0096
0097
0098 \ **ioctl**\
0099
0100  ignore 或 replace 语句应用于ioctl定义，如：
0101
0102  #define        VIDIOC_DBG_S_REGISTER    _IOW('V', 79, struct v4l2_dbg_register)
0103
0104
0105
0106 \ **define**\
0107
0108  ignore 或 replace 语句应用于在<C文件>中找到的任何其他 ``#define`` 。
0109
0110
0111
0112 \ **typedef**\
0113
0114  ignore 和 replace 语句应用于<C文件>中的typedef语句。
0115
0116
0117
0118 \ **struct**\
0119
0120  ignore 和 replace 语句应用于<C文件>中的结构体名称语句。
0121
0122
0123
0124 \ **enum**\
0125
0126  ignore 和 replace 语句应用于<C文件>中的枚举名称语句。
0127
0128
0129
0130 \ **symbol**\
0131
0132  ignore 和 replace 语句应用于<C文件>中的枚举值名称语句。
0133
0134  replace语句中， \ **new_value**\  会自动使用 \ **typedef**\ , \ **enum**\
0135  和 \ **struct**\ 类型的 :c:type: 引用；以及 \ **ioctl**\ , \ **define**\  和
0136  \ **symbol**\ 类型的  :ref: 。引用的类型也可以在replace语句中显式定义。
0137
0138
0139 示例
0140 ~~~~
0141
0142
0143 ignore define _VIDEODEV2_H
0144
0145
0146 忽略<C文件>中的 #define _VIDEODEV2_H 。
0147
0148 ignore symbol PRIVATE
0149
0150
0151 如下结构体：
0152
0153 enum foo { BAR1, BAR2, PRIVATE };
0154
0155 不会为 \ **PRIVATE**\ 生成交叉引用。
0156
0157 replace symbol BAR1 :c:type:\`foo\`
0158 replace symbol BAR2 :c:type:\`foo\`
0159
0160
0161 如下结构体：
0162
0163 enum foo { BAR1, BAR2, PRIVATE };
0164
0165 它会让BAR1和BAR2枚举符号交叉引用C域中的foo符号。
0166
0167
0168
0169 缺陷
0170 ~~~~
0171
0172
0173 请向Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。
0174
0175 中文翻译问题请找中文翻译维护者。
0176
0177
0178 版权
0179 ~~~~
0180
0181
0182 版权所有 (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
0183
0184 许可证 GPLv2：GNU GPL version 2 <https://gnu.org/licenses/gpl.html>
0185
0186 这是自由软件：你可以自由地修改和重新发布它。
0187 在法律允许的范围内，**不提供任何保证**。