如何写符合 kernel-doc 规范的注释

　　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.
　　
　　*/
　　<