Linux内核文档：包含 kernel-doc 注释
博主说
在上一篇文章，介绍了如何在源码中写符合 kernel-doc 规范的注释，这篇文章就告诉我们，如何在 .rst 文档中包含源码中书写的注释。
包含 kernel-doc 注释
文档注释可以包含在任何使用专用 kernel-doc Sphinx 指令扩展的 reStructuredText 文档中。
它采取这样的格式：
.. kernel-doc:: source
:option:
其中，source 指的是相对与内核树的源文件地址，而 option 支持以下选项。如果没有任何选项，则会包含源码内的所有符合 kernel-doc 的注释。
内核中使用 scripts/kernel-doc 的工具从源码中提取注释。
export:[source-pattern...]
包含所有用EXPORT_SYMBOL 和 EXPORT_SYMBOL_GPL 导出的函数的说明。可以是指定源文件，也可以通过模式匹配源文件。
文件的模式匹配尤其对那种注释在头文件中，但是 EXPORT_SYMBOL 在源文件中的情况。
例如：
.. kernel-doc:: lib/bitmap.c
:export:
.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.c
internal: [source-pattern …]
包含源码中未使用 XPORT_SYMBOL 和 EXPORT_SYMBOL_GPL 导出的所有函数或类型。
例如：
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:internal:
identifiers: [ function/type …]
包含源码中指定的函数或类型。如果没有指定，则默认包含所有源码中的函数和类型。
例如：
.. kernel-doc:: lib/bitmap.c
:identifiers: bitmap_parselist bitmap_parselist_user
.. kernel-doc:: lib/idr.c
:identifiers:
functions: [ function/type …]
这是 identifiers 的别称，已经弃用了
doc: title
包含源码中用 DOC: 标识的标题段落。标题中允许有空格，但不要括起来。标题仅用作段落的标识符，不会输出在文档中。请确保在.rst文档中有正确的标题。
例如：
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port
用 kernel-doc 生成 man 说明
可以在内核根目录执行：
$ scripts/kernel-doc -man \
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
| scripts/split-man.pl /tmp/man
一些旧版本的git可能不支持路径排除的语法变体，此时可以改用这样的命令：
$ scripts/kernel-doc -man \
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
| scripts/split-man.pl /tmp/man
$ scripts/kernel-doc -man \
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
| scripts/split-man.pl /tmp/man
