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