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