blob: a08819e904ed7871d8eac046653cf53cd6c9df4a (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
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>
这是自由软件：你可以自由地修改和重新发布它。
在法律允许的范围内，**不提供任何保证**。
|
