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
299 Writing kernel-doc comments
300 ===========================
302 In order to provide embedded, "C" friendly, easy to maintain, but consistent and
303 extractable overview, function and type documentation, the Linux kernel has
304 adopted a consistent style for documentation comments. The format for this
305 documentation is called the kernel-doc format, described below. This style
306 embeds the documentation within the source files, using a few simple conventions
307 for adding documentation paragraphs and documenting functions and their
308 parameters, structures and unions and their members, enumerations, and typedefs.
310 .. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen,
311 yet distinctively different, for historical reasons. The kernel source
312 contains tens of thousands of kernel-doc comments. Please stick to the style
315 The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
316 the documentation build to extract this embedded documentation into the various
317 HTML, PDF, and other format documents.
319 In order to provide good documentation of kernel functions and data structures,
320 please use the following conventions to format your kernel-doc comments in the
323 How to format kernel-doc comments
324 ---------------------------------
326 The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
327 comments so marked will be considered by the ``kernel-doc`` tool. Use it only
328 for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
329 should be used as the closing comment marker. The lines in between should be
330 prefixed by ``Â *Â `` (space star space).
332 The function and type kernel-doc comments should be placed just before the
333 function or type being described. The overview kernel-doc comments may be freely
334 placed at the top indentation level.
336 Example kernel-doc function comment::
339 * foobar() - Brief description of foobar.
340 * @arg: Description of argument of foobar.
342 * Longer description of foobar.
344 * Return: Description of return value of foobar.
348 The format is similar for documentation for structures, enums, paragraphs,
349 etc. See the sections below for details.
351 The kernel-doc structure is extracted from the comments, and proper `Sphinx C
352 Domain`_ function and type descriptions with anchors are generated for them. The
353 descriptions are filtered for special kernel-doc highlights and
354 cross-references. See below for details.
356 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
358 Highlights and cross-references
359 -------------------------------
361 The following special patterns are recognized in the kernel-doc comment
362 descriptive text and converted to proper reStructuredText markup and `Sphinx C
365 .. attention:: The below are **only** recognized within kernel-doc comments,
366 **not** within normal reStructuredText documents.
372 Name of a function parameter. (No cross-referencing, just formatting.)
375 Name of a constant. (No cross-referencing, just formatting.)
378 Name of an environment variable. (No cross-referencing, just formatting.)
389 ``&struct_name->member`` or ``&struct_name.member``
390 Structure or union member reference. The cross-reference will be to the struct
391 or union definition, not the member directly.
394 A generic type reference. Prefer using the full reference described above
395 instead. This is mostly for legacy comments.
397 Cross-referencing from reStructuredText
398 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
402 To cross-reference the functions and types defined in the kernel-doc comments
403 from reStructuredText documents, please use the `Sphinx C Domain`_
404 references. For example::
406 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
408 While the type reference works with just the type name, without the
409 struct/union/enum/typedef part in front, you may want to use::
411 See :c:type:`struct foo <foo>`.
412 See :c:type:`union bar <bar>`.
413 See :c:type:`enum baz <baz>`.
414 See :c:type:`typedef meh <meh>`.
416 This will produce prettier links, and is in line with how kernel-doc does the
419 For further details, please refer to the `Sphinx C Domain`_ documentation.
421 Function documentation
422 ----------------------
426 The general format of a function and function-like macro kernel-doc comment is::
429 * function_name() - Brief description of function.
430 * @arg1: Describe the first argument.
431 * @arg2: Describe the second argument.
432 * One can provide multiple line descriptions
435 * A longer description, with more discussion of the function function_name()
436 * that might be useful to those using or modifying it. Begins with an
437 * empty comment line, and may include additional embedded empty
440 * The longer description may have multiple paragraphs.
442 * Return: Describe the return value of foobar.
444 * The return value description can also have multiple paragraphs, and should
445 * be placed at the end of the comment block.
448 The brief description following the function name may span multiple lines, and
449 ends with an ``@argument:`` description, a blank comment line, or the end of the
452 The kernel-doc function comments describe each parameter to the function, in
453 order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
454 must begin on the very next line following the opening brief function
455 description line, with no intervening blank comment lines. The ``@argument:``
456 descriptions may span multiple lines. The continuation lines may contain
457 indentation. If a function parameter is ``...`` (varargs), it should be listed
458 in kernel-doc notation as: ``@...:``.
460 The return value, if any, should be described in a dedicated section at the end
461 of the comment starting with "Return:".
463 Structure, union, and enumeration documentation
464 -----------------------------------------------
466 The general format of a struct, union, and enum kernel-doc comment is::
469 * struct struct_name - Brief description.
470 * @member_name: Description of member member_name.
472 * Description of the structure.
475 Below, "struct" is used to mean structs, unions and enums, and "member" is used
476 to mean struct and union members as well as enumerations in an enum.
478 The brief description following the structure name may span multiple lines, and
479 ends with a ``@member:`` description, a blank comment line, or the end of the
482 The kernel-doc data structure comments describe each member of the structure, in
483 order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
484 begin on the very next line following the opening brief function description
485 line, with no intervening blank comment lines. The ``@member:`` descriptions may
486 span multiple lines. The continuation lines may contain indentation.
488 In-line member documentation comments
489 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
491 The structure members may also be documented in-line within the definition::
494 * struct foo - Brief description.
495 * @foo: The Foo member.
500 * @bar: The Bar member.
504 * @baz: The Baz member.
506 * Here, the member description may contain several paragraphs.
514 Inside a struct description, you can use the "private:" and "public:" comment
515 tags. Structure fields that are inside a "private:" area are not listed in the
516 generated output documentation. The "private:" and "public:" tags must begin
517 immediately following a ``/*`` comment marker. They may optionally include
518 comments between the ``:`` and the ending ``*/`` marker.
523 * struct my_struct - short description
532 /* private: internal use only */
537 Typedef documentation
538 ---------------------
540 The general format of a typedef kernel-doc comment is::
543 * typedef type_name - Brief description.
545 * Description of the type.
548 Overview documentation comments
549 -------------------------------
551 To facilitate having source code and comments close together, you can include
552 kernel-doc documentation blocks that are free-form comments instead of being
553 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
554 used for something like a theory of operation for a driver or library code, for
557 This is done by using a ``DOC:`` section keyword with a section title.
559 The general format of an overview or high-level documentation comment is::
562 * DOC: Theory of Operation
564 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
565 * want it to do, at any time. It reads your mind. Here's how it works.
569 * The only drawback to this gizmo is that is can sometimes damage
570 * hardware, software, or its subject(s).
573 The title following ``DOC:`` acts as a heading within the source file, but also
574 as an identifier for extracting the documentation comment. Thus, the title must
575 be unique within the file.
580 We definitely need kernel-doc formatted documentation for functions that are
581 exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
583 We also look to provide kernel-doc formatted documentation for functions
584 externally visible to other kernel files (not marked "static").
586 We also recommend providing kernel-doc formatted documentation for private (file
587 "static") routines, for consistency of kernel source code layout. But this is
588 lower priority and at the discretion of the MAINTAINER of that kernel source
591 Data structures visible in kernel include files should also be documented using
592 kernel-doc formatted comments.
594 DocBook XML [DEPRECATED]
595 ========================
599 This section describes the deprecated DocBook XML toolchain. Please do not
600 create new DocBook XML template files. Please consider converting existing
601 DocBook XML templates files to Sphinx/reStructuredText.
603 Converting DocBook to Sphinx
604 ----------------------------
608 Over time, we expect all of the documents under ``Documentation/DocBook`` to be
609 converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
610 enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
611 which uses ``pandoc`` under the hood. For example::
613 $ cd Documentation/sphinx
614 $ ./tmplcvt ../DocBook/in.tmpl ../out.rst
616 Then edit the resulting rst files to fix any remaining issues, and add the
617 document in the ``toctree`` in ``Documentation/index.rst``.
619 Components of the kernel-doc system
620 -----------------------------------
622 Many places in the source tree have extractable documentation in the form of
623 block comments above functions. The components of this system are:
625 - ``scripts/kernel-doc``
627 This is a perl script that hunts for the block comments and can mark them up
628 directly into reStructuredText, DocBook, man, text, and HTML. (No, not
631 - ``Documentation/DocBook/*.tmpl``
633 These are XML template files, which are normal XML files with special
634 place-holders for where the extracted documentation should go.
636 - ``scripts/docproc.c``
638 This is a program for converting XML template files into XML files. When a
639 file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
640 able to distinguish between internal and external functions.
642 It invokes kernel-doc, giving it the list of functions that are to be
645 Additionally it is used to scan the XML template files to locate all the files
646 referenced herein. This is used to generate dependency information as used by
651 The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
652 DocBook XML files, PostScript files, PDF files, and html files in
653 Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
655 - ``Documentation/DocBook/Makefile``
657 This is where C files are associated with SGML templates.
659 How to use kernel-doc comments in DocBook XML template files
660 ------------------------------------------------------------
662 DocBook XML template files (\*.tmpl) are like normal XML files, except that they
663 can contain escape sequences where extracted documentation should be inserted.
665 ``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
666 functions that are exported using ``EXPORT_SYMBOL``: the function list is
667 collected from files listed in ``Documentation/DocBook/Makefile``.
669 ``!I<filename>`` is replaced by the documentation for functions that are **not**
670 exported using ``EXPORT_SYMBOL``.
672 ``!D<filename>`` is used to name additional files to search for functions
673 exported using ``EXPORT_SYMBOL``.
675 ``!F<filename> <function [functions...]>`` is replaced by the documentation, in
676 ``<filename>``, for the functions listed.
678 ``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
679 section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
680 ``<section title>``; do not quote the ``<section title>``.
682 ``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
683 sections and documented functions, symbols, etc. are used. This makes sense to
684 use when you use ``!F`` or ``!P`` only and want to verify that all documentation