Documentation/translations/zh_CN/doc-guide/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并在代码和文档之间生成交叉引用，需要包含头文件和示例
  14 C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号，
  15 Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。
  16 :ref:`parse_headers.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。
  17 在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅
  18 ``Documentation/userspace-api/media/Makefile`` 。
  19
  20 .. _parse_headers_zh:
  21
  22 parse_headers.pl
  23 ----------------
  24
  25 脚本名称
  26 ~~~~~~~~
  27
  28
  29 parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档
  30 创建交叉引用。
  31
  32
  33 用法概要
  34 ~~~~~~~~
  35
  36
  37 \ **parse_headers.pl**\  [<选项>] <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
  77 ignore标记的语法为：
  78
  79
  80 ignore \ **type**\  \ **name**\
  81
  82 The \ **ignore**\  意味着它不会为类型为 \ **type**\ 的 \ **name**\ 符号生成
  83 交叉引用。
  84
  85
  86 replace标记的语法为：
  87
  88
  89 replace \ **type**\  \ **name**\  \ **new_value**\
  90
  91 The \ **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
 143 ignore define _VIDEODEV2_H
 144
 145
 146 忽略<C文件>中的 #define _VIDEODEV2_H 。
 147
 148 ignore symbol PRIVATE
 149
 150
 151 如下结构体：
 152
 153 enum foo { BAR1, BAR2, PRIVATE };
 154
 155 不会为 \ **PRIVATE**\ 生成交叉引用。
 156
 157 replace symbol BAR1 :c:type:\`foo\`
 158 replace symbol BAR2 :c:type:\`foo\`
 159
 160
 161 如下结构体：
 162
 163 enum 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 在法律允许的范围内，**不提供任何保证**。