Linux kernel sources: Documentation

Some documentation about the kernel sources is found under Documentation/ directory.

This documentation is complemented in the source files itself as kerneldoc comments (i.e. comments that start with /**),

Creating the documentation

Sphinx and .rst files

Linux uses Sphinx as tool to create the documentation from reStructuredText (files whose suffix is .rst).

Most .rst files are found below Documentation/, but some are also found below tools/bpf/bpftool/Documentation, tools/testing/selftests/bpf and drivers/staging/media/av7110.

Making the documentation

The documentation is made with one of the documentation targets, for example

$ make htmldocs

The created documentation is put into Documentation/output.

Making documentation prints lot of warnings:

./drivers/gpu/drm/amd/display/dc/dc.h:558: warning: Function parameter or member 'dispclk_khz' not described in 'dc_clocks'
./drivers/gpu/drm/amd/display/dc/dc.h:558: warning: Function parameter or member 'actual_dispclk_khz' not described in 'dc_clocks'
./drivers/gpu/drm/amd/display/dc/dc.h:558: warning: Function parameter or member 'dppclk_khz' not described in 'dc_clocks'
./drivers/gpu/drm/amd/display/dc/dc.h:558: warning: Function parameter or member 'actual_dppclk_khz' not described in 'dc_clocks'
./drivers/gpu/drm/amd/display/dc/dc.h:558: warning: Function parameter or member 'disp_dpp_voltage_level_khz' not described in 'dc_clocks'
./drivers/gpu/drm/amd/display/dc/dc.h:558: warning: Function parameter or member 'dcfclk_khz' not described in 'dc_clocks'
…
… etc. .etc. etc.
…

The variable SPHINXOPTS can be used to pass extra options to Sphinx, for example to obtain more verbose output:

$ make SPHINXOPTS=-v htmldocs

Kernel-doc comments

Kernel-doc comments are C comments that start with /** (and thus are similar to javadoc, gtk-doc or Doxygen).

Such comments can be interpreted by scripts/kernel-doc and scripts/split-man.pl.

scripts/find-unused-docs.sh detects files with kernel-doc comments for exported functions that are not included in documentation.

Kernel-doc comments should be written for (or is at least advisable for)

Every function exported to loadable modules using EXPORT_SYMBOL or EXPORT_SYMBOL_GPL
Functions and data structures in header files intended to be used in modules.
Functions externally visible to other kernel files (i. e. non static functions) («good practice»)
Functions marked static («recommendation»)

Guidelines to documenting rust code is found in Documentation/rust/general-information.rst.

Syntax and more for kernel-doc is described in Documentation/doc-guide/kernel-doc.rst.

.. kernel-doc ::

.. kernel-doc :: directives found in *.rst files.

For example, Documentation/gpu/vga-switcheroo.rst contains the following directive:

Modes of Use
============

Manual switching and manual power control
-----------------------------------------

.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
   :doc: Manual switching and manual power control

In drivers/gpu/vga/vga_switcheroo.c, there is a kernel doc where the referenced section is found with DOC: Manual switching and manual power control:

/**
 * DOC: Manual switching and manual power control
 *
 * In this mode of use, the file /sys/kernel/debug/vgaswitcheroo/switch

This RST section is then rendered in the Linux documentation page like so.

Other .. kernel-doc:: directives I've encountered include:

 .. kernel-doc:: kernel/livepatch/state.c
    :export:

 .. kernel-doc:: include/linux/livepatch.h
    :identifiers: klp_patch klp_object klp_func klp_callbacks klp_state

The documentation TODO list

Documentation/doc-guide/contributing.rst notes:

The documentation build currently spews out an unbelievable number of warnings. When you have that many, you might as well have none at all; people ignore them, and they will never notice when their work adds new ones. For this reason, eliminating warnings is one of the highest-priority tasks on the documentation TODO list.

Books

Apparently, there is an attempt to create a set of coherent books into which the scattered documentation should be merged:

	Located under `Documentation/`…
The Linux kernel user's and administrator's guide	`admin-guide`
Core API Documentation	`core-api`
Driver implementer's API guide	`driver-api`
The Linux kernel user-space API guide	`userspace-api`
How to write kernel documentation	`doc-guide`

Log files of patches

Apparently, some documentation of functionality can also be extracted from the log files that accompany a patch.

Non-typos that should not be fixed

Both, American and British spelling is allowed.

Off topic are debates such as if

a period must be followed by one or two spaces
the Oxford comma is allowed.