parse-headers.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3.. include:: ../disclaimer-zh_CN.rst
  4
  5:Original: Documentation/doc-guide/parse-headers.rst
  6
  7:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>
  8
  9=====================
 10包含用户空间API头文件
 11=====================
 12
 13有时，为了描述用户空间API并在代码和文档之间生成交叉引用，需要包含头文件和示例
 14C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号，
 15Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。
 16:ref:`parse_headers.py <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。
 17在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅
 18``Documentation/userspace-api/media/Makefile`` 。
 19
 20.. _parse_headers_zh:
 21
 22parse_headers.py
 23----------------
 24
 25脚本名称
 26~~~~~~~~
 27
 28
 29parse_headers.py——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档
 30创建交叉引用。
 31
 32
 33用法概要
 34~~~~~~~~
 35
 36
 37\ **parse_headers.py**\  [<选项>] <C文件> <输出文件> [<例外文件>]
 38
 39<选项> 可以是： --debug, --help 或 --usage 。
 40
 41
 42选项
 43~~~~
 44
 45
 46
 47\ **--debug**\
 48
 49 开启脚本详细模式，在调试时很有用。
 50
 51
 52\ **--usage**\
 53
 54 打印简短的帮助信息并退出。
 55
 56
 57
 58\ **--help**\
 59
 60 打印更详细的帮助信息并退出。
 61
 62
 63说明
 64~~~~
 65
 66通过C头文件或源文件（<C文件>）中为描述API的文档编写的带交叉引用的 ..预格式化
 67文本 块将文件转换成重构文本（RST）。它接受一个可选的<例外文件>，其中描述了
 68哪些元素将被忽略或指向非默认引用。
 69
 70输出被写入到<输出文件>。
 71
 72它能够识别定义、函数、结构体、typedef、枚举和枚举符号，并为它们创建交叉引用。
 73它还能够区分用于指定Linux ioctl的 ``#define`` 。
 74
 75<例外文件> 包含两种类型的语句： \ **ignore**\  或 \ **replace**\ .
 76
 77ignore标记的语法为：
 78
 79
 80ignore \ **type**\  \ **name**\
 81
 82The \ **ignore**\  意味着它不会为类型为 \ **type**\ 的 \ **name**\ 符号生成
 83交叉引用。
 84
 85
 86replace标记的语法为：
 87
 88
 89replace \ **type**\  \ **name**\  \ **new_value**\
 90
 91The \ **replace**\  味着它将为 \ **type**\ 类型的 \ **name**\ 符号生成交叉引
 92用，但是它将使用 \ **new_value**\ 来取代默认的替换规则。
 93
 94
 95这两种语句中， \ **type**\ 可以是以下任一项：
 96
 97
 98\ **ioctl**\
 99
100 ignore 或 replace 语句应用于ioctl定义，如：
101
102 #define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)
103
104
105
106\ **define**\
107
108 ignore 或 replace 语句应用于在<C文件>中找到的任何其他 ``#define`` 。
109
110
111
112\ **typedef**\
113
114 ignore 和 replace 语句应用于<C文件>中的typedef语句。
115
116
117
118\ **struct**\
119
120 ignore 和 replace 语句应用于<C文件>中的结构体名称语句。
121
122
123
124\ **enum**\
125
126 ignore 和 replace 语句应用于<C文件>中的枚举名称语句。
127
128
129
130\ **symbol**\
131
132 ignore 和 replace 语句应用于<C文件>中的枚举值名称语句。
133
134 replace语句中， \ **new_value**\  会自动使用 \ **typedef**\ , \ **enum**\
135 和 \ **struct**\ 类型的 :c:type: 引用；以及 \ **ioctl**\ , \ **define**\  和
136 \ **symbol**\ 类型的  :ref: 。引用的类型也可以在replace语句中显式定义。
137
138
139示例
140~~~~
141
142
143ignore define _VIDEODEV2_H
144
145
146忽略<C文件>中的 #define _VIDEODEV2_H 。
147
148ignore symbol PRIVATE
149
150
151如下结构体：
152
153enum foo { BAR1, BAR2, PRIVATE };
154
155不会为 \ **PRIVATE**\ 生成交叉引用。
156
157replace symbol BAR1 :c:type:\`foo\`
158replace symbol BAR2 :c:type:\`foo\`
159
160
161如下结构体：
162
163enum foo { BAR1, BAR2, PRIVATE };
164
165它会让BAR1和BAR2枚举符号交叉引用C域中的foo符号。
166
167
168
169缺陷
170~~~~
171
172
173请向Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。
174
175中文翻译问题请找中文翻译维护者。
176
177
178版权
179~~~~
180
181
182版权所有 (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
183
184许可证 GPLv2：GNU GPL version 2 <https://gnu.org/licenses/gpl.html>
185
186这是自由软件：你可以自由地修改和重新发布它。
187在法律允许的范围内，**不提供任何保证**。