How to make the kernel section 9 manpages which document functions, data structures, and headers?

Question

The kernel sources contain functions and data structures which are documented, for instance in 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, ...)

Instead of going through the sources every time, it would be useful to view those APIs as manpages and leverage this existing documentation framework.

---

How do you install/make the kernel section 9 manpages(/usr/share/man/man9) which document the aforementioned functions and data structures?

Answer 1

The content is parsed directly (see also this) from the source .c files¹:

In order to provide embedded, 'C' friendly, easy to maintain, but consistent and extractable documentation of the functions and data structures in the Linux kernel, the Linux kernel has adopted a consistent style for documenting functions and their parameters, and structures and their members.

The format for this documentation is called the kernel-doc format. It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.

This style embeds the documentation within the source files, using a few simple conventions. The scripts/kernel-doc perl script, some SGML templates in Documentation/DocBook, and other tools understand these conventions, and are used to extract this embedded documentation into various documents. [...]

The opening comment mark "/**" is reserved for kernel-doc comments. Only comments so marked will be considered by the kernel-doc scripts, and any comment so marked must be in kernel-doc format.

Which means only such formatted comments can be extracted this way and that you could leverage the kernel-doc Perl script used by the make process:

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

and therefore that you are not limited to the mandocs target:

After installation, "make psdocs", "make pdfdocs", "make htmldocs", or "make mandocs" will render the documentation in the requested format.

There are also driver specific text files in the kernel repository/source. More generally, their Linux man-pages project (man1 through man8) is available for download. On a last note kernel.org also maintains some output documentation.

---

^{1. The kernel is not the only case where such a technique is used to generate manpages. GNU coreutils is one such other case; most of its manpages are generated using the output of command --help the content of which is in the usage function the utility source file ( 1 2 ).}

Answer 2

Assuming you are using Ubuntu,

apt-get install linux-manual-3.2

or similar (pick the correct version). There is also another documentation package

apt-get install linux-doc

but this is html.

Answer 3

Download the kernel source code and in the source dir execute

make mandocs

After the man documents have been made, execute

make installmandocs

This will install the manual pages into /usr/local/man/man9/. Now you can view man pages by typing man <api-name>, or if you are editing in vim just press K over the API name.