.. 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> è¿™æ˜¯è‡ªç”±è½¯ä»¶ï¼šä½ å¯ä»¥è‡ªç”±åœ°ä¿®æ”¹å’Œé‡æ–°å‘布它。 在法律å…许的范围内,**ä¸æ供任何ä¿è¯**。