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.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。 17在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅 18``Documentation/userspace-api/media/Makefile`` 。 19 20.. _parse_headers_zh: 21 22parse_headers.pl 23---------------- 24 25脚本名称 26~~~~~~~~ 27 28 29parse_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 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在法律允许的范围内，**不提供任何保证**。 188