1 ==========================
2 Linux Kernel Documentation
3 ==========================
8 The Linux kernel uses `Sphinx`_ to generate pretty documentation from
9 `reStructuredText`_ files under ``Documentation``. To build the documentation in
10 HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
11 documentation is placed in ``Documentation/output``.
13 .. _Sphinx: http://www.sphinx-doc.org/
14 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
16 The reStructuredText files may contain directives to include structured
17 documentation comments, or kernel-doc comments, from source files. Usually these
18 are used to describe the functions and types and design of the code. The
19 kernel-doc comments have some special structure and formatting, but beyond that
20 they are also treated as reStructuredText.
22 There is also the deprecated DocBook toolchain to generate documentation from
23 DocBook XML template files under ``Documentation/DocBook``. The DocBook files
24 are to be converted to reStructuredText, and the toolchain is slated to be
27 Finally, there are thousands of plain text documentation files scattered around
28 ``Documentation``. Some of these will likely be converted to reStructuredText
29 over time, but the bulk of them will remain in plain text.
34 The usual way to generate the documentation is to run ``make htmldocs`` or
35 ``make pdfdocs``. There are also other formats available, see the documentation
36 section of ``make help``. The generated documentation is placed in
37 format-specific subdirectories under ``Documentation/output``.
39 To generate documentation, Sphinx (``sphinx-build``) must obviously be
40 installed. For prettier HTML output, the Read the Docs Sphinx theme
41 (``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also
42 needed. All of these are widely available and packaged in distributions.
44 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
45 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
48 To remove the generated documentation, run ``make cleandocs``.
53 Adding new documentation can be as simple as:
55 1. Add a new ``.rst`` file somewhere under ``Documentation``.
56 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
58 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
60 This is usually good enough for simple documentation (like the one you're
61 reading right now), but for larger documents it may be advisable to create a
62 subdirectory (or use an existing one). For example, the graphics subsystem
63 documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
64 and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
67 See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
68 with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
69 to get started with reStructuredText. There are also some `Sphinx specific
72 .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
73 .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
75 Specific guidelines for the kernel documentation
76 ------------------------------------------------
78 Here are some specific guidelines for the kernel documentation:
80 * Please don't go overboard with reStructuredText markup. Keep it simple.
82 * Please stick to this order of heading adornments:
84 1. ``=`` with overline for document title::
90 2. ``=`` for chapters::
95 3. ``-`` for sections::
100 4. ``~`` for subsections::
105 Although RST doesn't mandate a specific order ("Rather than imposing a fixed
106 number and order of section title adornment styles, the order enforced will be
107 the order as encountered."), having the higher levels the same overall makes
108 it easier to follow the documents.
114 The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
119 .. c:function:: int ioctl( int fd, int request )
121 The C domain of the kernel-doc has some additional features. E.g. you can
122 *rename* the reference name of a function with a common name like ``open`` or
127 .. c:function:: int ioctl( int fd, int request )
128 :name: VIDIOC_LOG_STATUS
130 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
131 ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
132 changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
136 :c:func:`VIDIOC_LOG_STATUS`
142 We recommend the use of *list table* formats. The *list table* formats are
143 double-stage lists. Compared to the ASCII-art they might not be as
145 readers of the text files. Their advantage is that they are easy to
146 create or modify and that the diff of a modification is much more meaningful,
147 because it is limited to the modified content.
149 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
150 some additional features:
152 * column-span: with the role ``cspan`` a cell can be extended through
155 * row-span: with the role ``rspan`` a cell can be extended through
158 * auto span rightmost cell of a table row over the missing cells on the right
159 side of that table-row. With Option ``:fill-cells:`` this behavior can
160 changed from *auto span* to *auto fill*, which automatically inserts (empty)
161 cells instead of spanning the last cell.
165 * ``:header-rows:`` [int] count of header rows
166 * ``:stub-columns:`` [int] count of stub columns
167 * ``:widths:`` [[int] [int] ... ] widths of columns
168 * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
172 * ``:cspan:`` [int] additional columns (*morecols*)
173 * ``:rspan:`` [int] additional rows (*morerows*)
175 The example below shows how to use this markup. The first level of the staged
176 list is the *table-row*. In the *table-row* there is only one markup allowed,
177 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
178 and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
183 .. flat-table:: table title
193 - field 1.2 with autospan
197 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
205 .. flat-table:: table title
215 - field 1.2 with autospan
219 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
226 Including kernel-doc comments
227 =============================
229 The Linux kernel source files may contain structured documentation comments, or
230 kernel-doc comments to describe the functions and types and design of the
231 code. The documentation comments may be included to any of the reStructuredText
232 documents using a dedicated kernel-doc Sphinx directive extension.
234 The kernel-doc directive is of the format::
236 .. kernel-doc:: source
239 The *source* is the path to a source file, relative to the kernel source
240 tree. The following directive options are supported:
242 export: *[source-pattern ...]*
243 Include documentation for all functions in *source* that have been exported
244 using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
245 of the files specified by *source-pattern*.
247 The *source-pattern* is useful when the kernel-doc comments have been placed
248 in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
249 the function definitions.
253 .. kernel-doc:: lib/bitmap.c
256 .. kernel-doc:: include/net/mac80211.h
257 :export: net/mac80211/*.c
259 internal: *[source-pattern ...]*
260 Include documentation for all functions and types in *source* that have
261 **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
262 in *source* or in any of the files specified by *source-pattern*.
266 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
270 Include documentation for the ``DOC:`` paragraph identified by *title* in
271 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
272 is only used as an identifier for the paragraph, and is not included in the
273 output. Please make sure to have an appropriate heading in the enclosing
274 reStructuredText document.
278 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
279 :doc: High Definition Audio over HDMI and Display Port
281 functions: *function* *[...]*
282 Include documentation for each *function* in *source*.
286 .. kernel-doc:: lib/bitmap.c
287 :functions: bitmap_parselist bitmap_parselist_user
289 Without options, the kernel-doc directive includes all documentation comments
290 from the source file.
292 The kernel-doc extension is included in the kernel source tree, at
293 ``Documentation/sphinx/kernel-doc.py``. Internally, it uses the
294 ``scripts/kernel-doc`` script to extract the documentation comments from the
297 Writing kernel-doc comments
298 ===========================
300 In order to provide embedded, "C" friendly, easy to maintain, but consistent and
301 extractable overview, function and type documentation, the Linux kernel has
302 adopted a consistent style for documentation comments. The format for this
303 documentation is called the kernel-doc format, described below. This style
304 embeds the documentation within the source files, using a few simple conventions
305 for adding documentation paragraphs and documenting functions and their
306 parameters, structures and unions and their members, enumerations, and typedefs.
308 .. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen,
309 yet distinctively different, for historical reasons. The kernel source
310 contains tens of thousands of kernel-doc comments. Please stick to the style
313 The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
314 the documentation build to extract this embedded documentation into the various
315 HTML, PDF, and other format documents.
317 In order to provide good documentation of kernel functions and data structures,
318 please use the following conventions to format your kernel-doc comments in the
321 How to format kernel-doc comments
322 ---------------------------------
324 The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
325 comments so marked will be considered by the ``kernel-doc`` tool. Use it only
326 for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
327 should be used as the closing comment marker. The lines in between should be
328 prefixed by ``Â *Â `` (space star space).
330 The function and type kernel-doc comments should be placed just before the
331 function or type being described. The overview kernel-doc comments may be freely
332 placed at the top indentation level.
334 Example kernel-doc function comment::
337 * foobar() - Brief description of foobar.
338 * @arg: Description of argument of foobar.
340 * Longer description of foobar.
342 * Return: Description of return value of foobar.
346 The format is similar for documentation for structures, enums, paragraphs,
347 etc. See the sections below for details.
349 The kernel-doc structure is extracted from the comments, and proper `Sphinx C
350 Domain`_ function and type descriptions with anchors are generated for them. The
351 descriptions are filtered for special kernel-doc highlights and
352 cross-references. See below for details.
354 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
356 Highlights and cross-references
357 -------------------------------
359 The following special patterns are recognized in the kernel-doc comment
360 descriptive text and converted to proper reStructuredText markup and `Sphinx C
363 .. attention:: The below are **only** recognized within kernel-doc comments,
364 **not** within normal reStructuredText documents.
370 Name of a function parameter. (No cross-referencing, just formatting.)
373 Name of a constant. (No cross-referencing, just formatting.)
376 Name of an environment variable. (No cross-referencing, just formatting.)
387 ``&struct_name->member`` or ``&struct_name.member``
388 Structure or union member reference. The cross-reference will be to the struct
389 or union definition, not the member directly.
392 A generic type reference. Prefer using the full reference described above
393 instead. This is mostly for legacy comments.
395 Cross-referencing from reStructuredText
396 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
398 To cross-reference the functions and types defined in the kernel-doc comments
399 from reStructuredText documents, please use the `Sphinx C Domain`_
400 references. For example::
402 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
404 While the type reference works with just the type name, without the
405 struct/union/enum/typedef part in front, you may want to use::
407 See :c:type:`struct foo <foo>`.
408 See :c:type:`union bar <bar>`.
409 See :c:type:`enum baz <baz>`.
410 See :c:type:`typedef meh <meh>`.
412 This will produce prettier links, and is in line with how kernel-doc does the
415 For further details, please refer to the `Sphinx C Domain`_ documentation.
417 Function documentation
418 ----------------------
420 The general format of a function and function-like macro kernel-doc comment is::
423 * function_name() - Brief description of function.
424 * @arg1: Describe the first argument.
425 * @arg2: Describe the second argument.
426 * One can provide multiple line descriptions
429 * A longer description, with more discussion of the function function_name()
430 * that might be useful to those using or modifying it. Begins with an
431 * empty comment line, and may include additional embedded empty
434 * The longer description may have multiple paragraphs.
436 * Return: Describe the return value of foobar.
438 * The return value description can also have multiple paragraphs, and should
439 * be placed at the end of the comment block.
442 The brief description following the function name may span multiple lines, and
443 ends with an ``@argument:`` description, a blank comment line, or the end of the
446 The kernel-doc function comments describe each parameter to the function, in
447 order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
448 must begin on the very next line following the opening brief function
449 description line, with no intervening blank comment lines. The ``@argument:``
450 descriptions may span multiple lines. The continuation lines may contain
451 indentation. If a function parameter is ``...`` (varargs), it should be listed
452 in kernel-doc notation as: ``@...:``.
454 The return value, if any, should be described in a dedicated section at the end
455 of the comment starting with "Return:".
457 Structure, union, and enumeration documentation
458 -----------------------------------------------
460 The general format of a struct, union, and enum kernel-doc comment is::
463 * struct struct_name - Brief description.
464 * @member_name: Description of member member_name.
466 * Description of the structure.
469 Below, "struct" is used to mean structs, unions and enums, and "member" is used
470 to mean struct and union members as well as enumerations in an enum.
472 The brief description following the structure name may span multiple lines, and
473 ends with a ``@member:`` description, a blank comment line, or the end of the
476 The kernel-doc data structure comments describe each member of the structure, in
477 order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
478 begin on the very next line following the opening brief function description
479 line, with no intervening blank comment lines. The ``@member:`` descriptions may
480 span multiple lines. The continuation lines may contain indentation.
482 In-line member documentation comments
483 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
485 The structure members may also be documented in-line within the definition::
488 * struct foo - Brief description.
489 * @foo: The Foo member.
494 * @bar: The Bar member.
498 * @baz: The Baz member.
500 * Here, the member description may contain several paragraphs.
508 Inside a struct description, you can use the "private:" and "public:" comment
509 tags. Structure fields that are inside a "private:" area are not listed in the
510 generated output documentation. The "private:" and "public:" tags must begin
511 immediately following a ``/*`` comment marker. They may optionally include
512 comments between the ``:`` and the ending ``*/`` marker.
517 * struct my_struct - short description
526 /* private: internal use only */
531 Typedef documentation
532 ---------------------
534 The general format of a typedef kernel-doc comment is::
537 * typedef type_name - Brief description.
539 * Description of the type.
542 Overview documentation comments
543 -------------------------------
545 To facilitate having source code and comments close together, you can include
546 kernel-doc documentation blocks that are free-form comments instead of being
547 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
548 used for something like a theory of operation for a driver or library code, for
551 This is done by using a ``DOC:`` section keyword with a section title.
553 The general format of an overview or high-level documentation comment is::
556 * DOC: Theory of Operation
558 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
559 * want it to do, at any time. It reads your mind. Here's how it works.
563 * The only drawback to this gizmo is that is can sometimes damage
564 * hardware, software, or its subject(s).
567 The title following ``DOC:`` acts as a heading within the source file, but also
568 as an identifier for extracting the documentation comment. Thus, the title must
569 be unique within the file.
574 We definitely need kernel-doc formatted documentation for functions that are
575 exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
577 We also look to provide kernel-doc formatted documentation for functions
578 externally visible to other kernel files (not marked "static").
580 We also recommend providing kernel-doc formatted documentation for private (file
581 "static") routines, for consistency of kernel source code layout. But this is
582 lower priority and at the discretion of the MAINTAINER of that kernel source
585 Data structures visible in kernel include files should also be documented using
586 kernel-doc formatted comments.
588 DocBook XML [DEPRECATED]
589 ========================
593 This section describes the deprecated DocBook XML toolchain. Please do not
594 create new DocBook XML template files. Please consider converting existing
595 DocBook XML templates files to Sphinx/reStructuredText.
597 Converting DocBook to Sphinx
598 ----------------------------
600 Over time, we expect all of the documents under ``Documentation/DocBook`` to be
601 converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
602 enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
603 which uses ``pandoc`` under the hood. For example::
605 $ cd Documentation/sphinx
606 $ ./tmplcvt ../DocBook/in.tmpl ../out.rst
608 Then edit the resulting rst files to fix any remaining issues, and add the
609 document in the ``toctree`` in ``Documentation/index.rst``.
611 Components of the kernel-doc system
612 -----------------------------------
614 Many places in the source tree have extractable documentation in the form of
615 block comments above functions. The components of this system are:
617 - ``scripts/kernel-doc``
619 This is a perl script that hunts for the block comments and can mark them up
620 directly into reStructuredText, DocBook, man, text, and HTML. (No, not
623 - ``Documentation/DocBook/*.tmpl``
625 These are XML template files, which are normal XML files with special
626 place-holders for where the extracted documentation should go.
628 - ``scripts/docproc.c``
630 This is a program for converting XML template files into XML files. When a
631 file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
632 able to distinguish between internal and external functions.
634 It invokes kernel-doc, giving it the list of functions that are to be
637 Additionally it is used to scan the XML template files to locate all the files
638 referenced herein. This is used to generate dependency information as used by
643 The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
644 DocBook XML files, PostScript files, PDF files, and html files in
645 Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
647 - ``Documentation/DocBook/Makefile``
649 This is where C files are associated with SGML templates.
651 How to use kernel-doc comments in DocBook XML template files
652 ------------------------------------------------------------
654 DocBook XML template files (\*.tmpl) are like normal XML files, except that they
655 can contain escape sequences where extracted documentation should be inserted.
657 ``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
658 functions that are exported using ``EXPORT_SYMBOL``: the function list is
659 collected from files listed in ``Documentation/DocBook/Makefile``.
661 ``!I<filename>`` is replaced by the documentation for functions that are **not**
662 exported using ``EXPORT_SYMBOL``.
664 ``!D<filename>`` is used to name additional files to search for functions
665 exported using ``EXPORT_SYMBOL``.
667 ``!F<filename> <function [functions...]>`` is replaced by the documentation, in
668 ``<filename>``, for the functions listed.
670 ``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
671 section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
672 ``<section title>``; do not quote the ``<section title>``.
674 ``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
675 sections and documented functions, symbols, etc. are used. This makes sense to
676 use when you use ``!F`` or ``!P`` only and want to verify that all documentation