17e402ef5SWu XiangCheng.. SPDX-License-Identifier: GPL-2.0 27e402ef5SWu XiangCheng 37e402ef5SWu XiangCheng.. include:: ../disclaimer-zh_CN.rst 47e402ef5SWu XiangCheng 57e402ef5SWu XiangCheng:Original: Documentation/doc-guide/parse-headers.rst 67e402ef5SWu XiangCheng 77e402ef5SWu XiangCheng:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> 87e402ef5SWu XiangCheng 97e402ef5SWu XiangCheng===================== 107e402ef5SWu XiangCheng包含用户空间API头文件 117e402ef5SWu XiangCheng===================== 127e402ef5SWu XiangCheng 137e402ef5SWu XiangCheng有时,为了描述用户空间API并在代码和文档之间生成交叉引用,需要包含头文件和示例 147e402ef5SWu XiangChengC代码。为用户空间API文件添加交叉引用还有一个好处:如果在文档中找不到相应符号, 157e402ef5SWu XiangChengSphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。 167e402ef5SWu XiangCheng:ref:`parse_headers.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。 177e402ef5SWu XiangCheng在构建文档时,必须通过Makefile调用它。有关如何在内核树中使用它的示例,请参阅 187e402ef5SWu XiangCheng``Documentation/userspace-api/media/Makefile`` 。 197e402ef5SWu XiangCheng 207e402ef5SWu XiangCheng.. _parse_headers_zh: 217e402ef5SWu XiangCheng 227e402ef5SWu XiangChengparse_headers.pl 237e402ef5SWu XiangCheng---------------- 247e402ef5SWu XiangCheng 257e402ef5SWu XiangCheng脚本名称 267e402ef5SWu XiangCheng~~~~~~~~ 277e402ef5SWu XiangCheng 287e402ef5SWu XiangCheng 297e402ef5SWu XiangChengparse_headers.pl——解析一个C文件,识别函数、结构体、枚举、定义并对Sphinx文档 307e402ef5SWu XiangCheng创建交叉引用。 317e402ef5SWu XiangCheng 327e402ef5SWu XiangCheng 337e402ef5SWu XiangCheng用法概要 347e402ef5SWu XiangCheng~~~~~~~~ 357e402ef5SWu XiangCheng 367e402ef5SWu XiangCheng 377e402ef5SWu XiangCheng\ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>] 387e402ef5SWu XiangCheng 397e402ef5SWu XiangCheng<选项> 可以是: --debug, --help 或 --usage 。 407e402ef5SWu XiangCheng 417e402ef5SWu XiangCheng 427e402ef5SWu XiangCheng选项 437e402ef5SWu XiangCheng~~~~ 447e402ef5SWu XiangCheng 457e402ef5SWu XiangCheng 467e402ef5SWu XiangCheng 477e402ef5SWu XiangCheng\ **--debug**\ 487e402ef5SWu XiangCheng 497e402ef5SWu XiangCheng 开启脚本详细模式,在调试时很有用。 507e402ef5SWu XiangCheng 517e402ef5SWu XiangCheng 527e402ef5SWu XiangCheng\ **--usage**\ 537e402ef5SWu XiangCheng 547e402ef5SWu XiangCheng 打印简短的帮助信息并退出。 557e402ef5SWu XiangCheng 567e402ef5SWu XiangCheng 577e402ef5SWu XiangCheng 587e402ef5SWu XiangCheng\ **--help**\ 597e402ef5SWu XiangCheng 607e402ef5SWu XiangCheng 打印更详细的帮助信息并退出。 617e402ef5SWu XiangCheng 627e402ef5SWu XiangCheng 637e402ef5SWu XiangCheng说明 647e402ef5SWu XiangCheng~~~~ 657e402ef5SWu XiangCheng 667e402ef5SWu XiangCheng通过C头文件或源文件(<C文件>)中为描述API的文档编写的带交叉引用的 ..预格式化 677e402ef5SWu XiangCheng文本 块将文件转换成重构文本(RST)。它接受一个可选的<例外文件>,其中描述了 687e402ef5SWu XiangCheng哪些元素将被忽略或指向非默认引用。 697e402ef5SWu XiangCheng 707e402ef5SWu XiangCheng输出被写入到<输出文件>。 717e402ef5SWu XiangCheng 727e402ef5SWu XiangCheng它能够识别定义、函数、结构体、typedef、枚举和枚举符号,并为它们创建交叉引用。 737e402ef5SWu XiangCheng它还能够区分用于指定Linux ioctl的 ``#define`` 。 747e402ef5SWu XiangCheng 757e402ef5SWu XiangCheng<例外文件> 包含两种类型的语句: \ **ignore**\ 或 \ **replace**\ . 767e402ef5SWu XiangCheng 777e402ef5SWu XiangChengignore标记的语法为: 787e402ef5SWu XiangCheng 797e402ef5SWu XiangCheng 807e402ef5SWu XiangChengignore \ **type**\ \ **name**\ 817e402ef5SWu XiangCheng 827e402ef5SWu XiangChengThe \ **ignore**\ 意味着它不会为类型为 \ **type**\ 的 \ **name**\ 符号生成 837e402ef5SWu XiangCheng交叉引用。 847e402ef5SWu XiangCheng 857e402ef5SWu XiangCheng 867e402ef5SWu XiangChengreplace标记的语法为: 877e402ef5SWu XiangCheng 887e402ef5SWu XiangCheng 897e402ef5SWu XiangChengreplace \ **type**\ \ **name**\ \ **new_value**\ 907e402ef5SWu XiangCheng 917e402ef5SWu XiangChengThe \ **replace**\ 味着它将为 \ **type**\ 类型的 \ **name**\ 符号生成交叉引 927e402ef5SWu XiangCheng用,但是它将使用 \ **new_value**\ 来取代默认的替换规则。 937e402ef5SWu XiangCheng 947e402ef5SWu XiangCheng 957e402ef5SWu XiangCheng这两种语句中, \ **type**\ 可以是以下任一项: 967e402ef5SWu XiangCheng 977e402ef5SWu XiangCheng 987e402ef5SWu XiangCheng\ **ioctl**\ 997e402ef5SWu XiangCheng 1007e402ef5SWu XiangCheng ignore 或 replace 语句应用于ioctl定义,如: 1017e402ef5SWu XiangCheng 1027e402ef5SWu XiangCheng #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) 1037e402ef5SWu XiangCheng 1047e402ef5SWu XiangCheng 1057e402ef5SWu XiangCheng 1067e402ef5SWu XiangCheng\ **define**\ 1077e402ef5SWu XiangCheng 1087e402ef5SWu XiangCheng ignore 或 replace 语句应用于在<C文件>中找到的任何其他 ``#define`` 。 1097e402ef5SWu XiangCheng 1107e402ef5SWu XiangCheng 1117e402ef5SWu XiangCheng 1127e402ef5SWu XiangCheng\ **typedef**\ 1137e402ef5SWu XiangCheng 1147e402ef5SWu XiangCheng ignore 和 replace 语句应用于<C文件>中的typedef语句。 1157e402ef5SWu XiangCheng 1167e402ef5SWu XiangCheng 1177e402ef5SWu XiangCheng 1187e402ef5SWu XiangCheng\ **struct**\ 1197e402ef5SWu XiangCheng 1207e402ef5SWu XiangCheng ignore 和 replace 语句应用于<C文件>中的结构体名称语句。 1217e402ef5SWu XiangCheng 1227e402ef5SWu XiangCheng 1237e402ef5SWu XiangCheng 1247e402ef5SWu XiangCheng\ **enum**\ 1257e402ef5SWu XiangCheng 1267e402ef5SWu XiangCheng ignore 和 replace 语句应用于<C文件>中的枚举名称语句。 1277e402ef5SWu XiangCheng 1287e402ef5SWu XiangCheng 1297e402ef5SWu XiangCheng 1307e402ef5SWu XiangCheng\ **symbol**\ 1317e402ef5SWu XiangCheng 1327e402ef5SWu XiangCheng ignore 和 replace 语句应用于<C文件>中的枚举值名称语句。 1337e402ef5SWu XiangCheng 1347e402ef5SWu XiangCheng replace语句中, \ **new_value**\ 会自动使用 \ **typedef**\ , \ **enum**\ 1357e402ef5SWu XiangCheng 和 \ **struct**\ 类型的 :c:type: 引用;以及 \ **ioctl**\ , \ **define**\ 和 1367e402ef5SWu XiangCheng \ **symbol**\ 类型的 :ref: 。引用的类型也可以在replace语句中显式定义。 1377e402ef5SWu XiangCheng 1387e402ef5SWu XiangCheng 1397e402ef5SWu XiangCheng示例 1407e402ef5SWu XiangCheng~~~~ 1417e402ef5SWu XiangCheng 1427e402ef5SWu XiangCheng 1437e402ef5SWu XiangChengignore define _VIDEODEV2_H 1447e402ef5SWu XiangCheng 1457e402ef5SWu XiangCheng 1467e402ef5SWu XiangCheng忽略<C文件>中的 #define _VIDEODEV2_H 。 1477e402ef5SWu XiangCheng 1487e402ef5SWu XiangChengignore symbol PRIVATE 1497e402ef5SWu XiangCheng 1507e402ef5SWu XiangCheng 1517e402ef5SWu XiangCheng如下结构体: 1527e402ef5SWu XiangCheng 1537e402ef5SWu XiangChengenum foo { BAR1, BAR2, PRIVATE }; 1547e402ef5SWu XiangCheng 1557e402ef5SWu XiangCheng不会为 \ **PRIVATE**\ 生成交叉引用。 1567e402ef5SWu XiangCheng 1577e402ef5SWu XiangChengreplace symbol BAR1 :c:type:\`foo\` 1587e402ef5SWu XiangChengreplace symbol BAR2 :c:type:\`foo\` 1597e402ef5SWu XiangCheng 1607e402ef5SWu XiangCheng 1617e402ef5SWu XiangCheng如下结构体: 1627e402ef5SWu XiangCheng 1637e402ef5SWu XiangChengenum foo { BAR1, BAR2, PRIVATE }; 1647e402ef5SWu XiangCheng 1657e402ef5SWu XiangCheng它会让BAR1和BAR2枚举符号交叉引用C域中的foo符号。 1667e402ef5SWu XiangCheng 1677e402ef5SWu XiangCheng 1687e402ef5SWu XiangCheng 1697e402ef5SWu XiangCheng缺陷 1707e402ef5SWu XiangCheng~~~~ 1717e402ef5SWu XiangCheng 1727e402ef5SWu XiangCheng 1737e402ef5SWu XiangCheng请向Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。 1747e402ef5SWu XiangCheng 1757e402ef5SWu XiangCheng中文翻译问题请找中文翻译维护者。 1767e402ef5SWu XiangCheng 1777e402ef5SWu XiangCheng 1787e402ef5SWu XiangCheng版权 1797e402ef5SWu XiangCheng~~~~ 1807e402ef5SWu XiangCheng 1817e402ef5SWu XiangCheng 1827e402ef5SWu XiangCheng版权所有 (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> 1837e402ef5SWu XiangCheng 1847e402ef5SWu XiangCheng许可证 GPLv2:GNU GPL version 2 <https://gnu.org/licenses/gpl.html> 1857e402ef5SWu XiangCheng 1867e402ef5SWu XiangCheng这是自由软件:你可以自由地修改和重新发布它。 187*9a18473cSWu XiangCheng在法律允许的范围内,**不提供任何保证**。 188