如何制作包含函数、数据结构和头文件的内核第 9 部分联机帮助页？

Question

内核源代码包含记录在案的函数和数据结构，例如panic.c：

/**
 *  panic - halt the system
 *  @fmt: The text string to print
 *
 *  Display a message, then perform cleanups.
 *
 *  This function never returns.
 */
void panic(const char *fmt, ...)

与其每次都浏览源代码，不如将这些 API 视为联机帮助页并利用现有的文档框架。

---

您如何安装/制作记录上述函数和数据结构的内核第 9 部分联机帮助页( /usr/share/man/man9)？

Answer 1

内容是从源.c 文件¹直接解析的（另请参阅此）：

为了提供嵌入式、'C' 友好、易于维护、但一致且可提取的 Linux 内核中函数和数据结构的文档，Linux 内核采用了一致的风格来记录函数及其参数、结构及其成员。

本文档的格式称为内核文档格式。它记录在此 Documentation/kernel-doc-nano-HOWTO.txt 文件中。

这种风格使用一些简单的约定将文档嵌入到源文件中。scripts/kernel-doc perl 脚本、Documentation/DocBook 中的一些 SGML 模板以及其他工具都理解这些约定，并用于将这种嵌入的文档提取到各种文档中。[...]

开始注释标记“/**”是为内核文档注释保留的。内核文档脚本只会考虑这样标记的注释，并且任何这样标记的注释都必须是内核文档格式。

这意味着只能以这种方式提取这种格式化的注释，并且您可以利用该过程使用的Perl脚本：kernel-doc make

kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  [ -no-doc-sections ]
  [ -function funcname [ -function funcname ...] ]
  c file(s)s > outputfile

因此，您不仅限于mandocs 目标：

安装后，“make psdocs”、“make pdfdocs”、“make htmldocs”或“make mandocs”将以请求的格式呈现文档。

内核存储库/源中还有特定于驱动程序的文本文件。更一般地说，他们的Linux 手册页项目（man1到man8）可供下载。最后一点，kernel.org 还维护了一些输出文档。

^{1. 内核并不是使用这种技术生成联机帮助页的唯一情况。GNU coreutils就是另一种情况；其大部分手册页都产生使用的输出command --help，其中在所述内容的使用功能的实用程序的源文件（1 2）。}

Answer 2

假设您使用的是 Ubuntu，

apt-get install linux-manual-3.2

或类似（选择正确的版本）。还有另一个文档包

apt-get install linux-doc

但这是 html。