Linux内核文档:如何写符合 kernel-doc 规范的注释
简介#
Linux内核使用 Sphinx 实现把 Documentation 目录下的 reStructuredText 文件转换为非常漂亮的文档。文档既可以通过 make htmldocs 转换成 HTML 格式,也可以通过 make pdfdocs 转换为 PDF 格式。 转换生成的文档存放于 Documentation/output 目录下。
Linux内核强大的文档功能,除了直接转换 .rst文档之外,还能从源码中汲取API说明,结构体说明等信息。当然要做到这样,源码的注释是有一定要求的。而这篇文档,就是介绍如何写符合 kernel-doc 格式要求的注释。
英文版原文,根据个人理解做的翻译,如果有翻译错误的地方,请告知。
注释概述#
符合 kernel-doc 的注释,都需要从 /** 开始,其后每一行内容都以 *开头,最后是 */ 表示结束。例如:
Copy
/**
* This is a sample of comment
*/
对于函数和类型的注释,必须放在函数和类型之前,以便于别人在修改代码的时候,可以顺手把注释也改了。对概述类型的注释,可以放到文件顶部的位置。
Linux内核有提供一个工具用于对 kernel-doc 的格式进行检查,例如:
Copy
$ scripts/kernel-doc -v -none drivers/foo/bar.c
当然,在编译的时候,如果添加以下的选项,也会检查文档的格式:
Copy
make W=n
函数文档#
规范的格式示例如下:
Copy
/**
* function_name() - Brief description of function.
* @arg1: Describe the first argument.
* @arg2: Describe the second argument.
* One can provide multiple line descriptions
* for arguments.
*
* A longer description, with more discussion of the function function_name()
* that might be useful to those using or modifying it. Begins with an
* empty comment line, and may include additional embedded empty
* comment lines.
*
* The longer description may have multiple paragraphs.
*
* Context: Describes whether the function can sleep, what locks it takes,
* releases, or expects to be held. It can extend over multiple
* lines.
* Return: Describe the return value of function_name.
*
* The return value description can also have multiple paragraphs, and should
* be placed at the end of the comment block.
*/
<
如何写符合 kernel-doc 规范的注释
最新推荐文章于 2021-12-09 09:36:47 发布
本文档介绍了如何编写符合kernel-doc格式的注释,以供Linux内核文档转换和源码分析。注释应从/**开始,以*/结束,详细描述函数、参数、上下文和返回值。内核提供了kernel-doc工具检查注释格式,并在编译时检查文档。函数注释包括函数简介、参数描述、上下文和返回值,结构体、联合和枚举的注释类似,支持嵌套结构和匿名结构的描述。还提到了typedef注释以及如何使用高亮和交叉索引。
摘要由CSDN通过智能技术生成