Search notes:

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)
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

See also

The files under Documentation/. The main table of content (TOC) file is Documentation/index.rst (of which the latest generated output is found at www.kernel.org/doc/html/latest/).
Documentation/doc-guide/contributing.rst lays out guidelines related to improving the kernel documentation.
The Linux man-pages are maintained separately from the Linux documentation.

Links

The mailing list to discuss documentation subjects is linux-doc at vger.kernel.org.
Documentation for specific groups of users:

Index