linux/Documentation/kernel-documentation.rst
<<
>>
Prefs
   1==========================
   2Linux Kernel Documentation
   3==========================
   4
   5Introduction
   6============
   7
   8The Linux kernel uses `Sphinx`_ to generate pretty documentation from
   9`reStructuredText`_ files under ``Documentation``. To build the documentation in
  10HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
  11documentation is placed in ``Documentation/output``.
  12
  13.. _Sphinx: http://www.sphinx-doc.org/
  14.. _reStructuredText: http://docutils.sourceforge.net/rst.html
  15
  16The reStructuredText files may contain directives to include structured
  17documentation comments, or kernel-doc comments, from source files. Usually these
  18are used to describe the functions and types and design of the code. The
  19kernel-doc comments have some special structure and formatting, but beyond that
  20they are also treated as reStructuredText.
  21
  22There is also the deprecated DocBook toolchain to generate documentation from
  23DocBook XML template files under ``Documentation/DocBook``. The DocBook files
  24are to be converted to reStructuredText, and the toolchain is slated to be
  25removed.
  26
  27Finally, there are thousands of plain text documentation files scattered around
  28``Documentation``. Some of these will likely be converted to reStructuredText
  29over time, but the bulk of them will remain in plain text.
  30
  31Sphinx Build
  32============
  33
  34The usual way to generate the documentation is to run ``make htmldocs`` or
  35``make pdfdocs``. There are also other formats available, see the documentation
  36section of ``make help``. The generated documentation is placed in
  37format-specific subdirectories under ``Documentation/output``.
  38
  39To generate documentation, Sphinx (``sphinx-build``) must obviously be
  40installed. For prettier HTML output, the Read the Docs Sphinx theme
  41(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also
  42needed. All of these are widely available and packaged in distributions.
  43
  44To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
  45variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
  46output.
  47
  48To remove the generated documentation, run ``make cleandocs``.
  49
  50Writing Documentation
  51=====================
  52
  53Adding new documentation can be as simple as:
  54
  551. Add a new ``.rst`` file somewhere under ``Documentation``.
  562. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
  57
  58.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
  59
  60This is usually good enough for simple documentation (like the one you're
  61reading right now), but for larger documents it may be advisable to create a
  62subdirectory (or use an existing one). For example, the graphics subsystem
  63documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
  64and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
  65the main index.
  66
  67See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
  68with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
  69to get started with reStructuredText. There are also some `Sphinx specific
  70markup constructs`_.
  71
  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
  74
  75Specific guidelines for the kernel documentation
  76------------------------------------------------
  77
  78Here are some specific guidelines for the kernel documentation:
  79
  80* Please don't go overboard with reStructuredText markup. Keep it simple.
  81
  82* Please stick to this order of heading adornments:
  83
  84  1. ``=`` with overline for document title::
  85
  86       ==============
  87       Document title
  88       ==============
  89
  90  2. ``=`` for chapters::
  91
  92       Chapters
  93       ========
  94
  95  3. ``-`` for sections::
  96
  97       Section
  98       -------
  99
 100  4. ``~`` for subsections::
 101
 102       Subsection
 103       ~~~~~~~~~~
 104
 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.
 109
 110
 111the C domain
 112------------
 113
 114The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
 115function prototype:
 116
 117.. code-block:: rst
 118
 119    .. c:function:: int ioctl( int fd, int request )
 120
 121The 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
 123``ioctl``:
 124
 125.. code-block:: rst
 126
 127     .. c:function:: int ioctl( int fd, int request )
 128        :name: VIDIOC_LOG_STATUS
 129
 130The 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
 132changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
 133
 134.. code-block:: rst
 135
 136     :c:func:`VIDIOC_LOG_STATUS`
 137
 138
 139list tables
 140-----------
 141
 142We recommend the use of *list table* formats. The *list table* formats are
 143double-stage lists. Compared to the ASCII-art they might not be as
 144comfortable for 
 145readers of the text files. Their advantage is that they are easy to
 146create or modify and that the diff of a modification is much more meaningful,
 147because it is limited to the modified content.
 148
 149The ``flat-table`` is a double-stage list similar to the ``list-table`` with
 150some additional features:
 151
 152* column-span: with the role ``cspan`` a cell can be extended through
 153  additional columns
 154
 155* row-span: with the role ``rspan`` a cell can be extended through
 156  additional rows
 157
 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.
 162
 163options:
 164
 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
 169
 170roles:
 171
 172* ``:cspan:`` [int] additional columns (*morecols*)
 173* ``:rspan:`` [int] additional rows (*morerows*)
 174
 175The example below shows how to use this markup.  The first level of the staged
 176list is the *table-row*. In the *table-row* there is only one markup allowed,
 177the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
 178and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
 179<last row>`).
 180
 181.. code-block:: rst
 182
 183   .. flat-table:: table title
 184      :widths: 2 1 1 3
 185
 186      * - head col 1
 187        - head col 2
 188        - head col 3
 189        - head col 4
 190
 191      * - column 1
 192        - field 1.1
 193        - field 1.2 with autospan
 194
 195      * - column 2
 196        - field 2.1
 197        - :rspan:`1` :cspan:`1` field 2.2 - 3.3
 198
 199      * .. _`last row`:
 200
 201        - column 3
 202
 203Rendered as:
 204
 205   .. flat-table:: table title
 206      :widths: 2 1 1 3
 207
 208      * - head col 1
 209        - head col 2
 210        - head col 3
 211        - head col 4
 212
 213      * - column 1
 214        - field 1.1
 215        - field 1.2 with autospan
 216
 217      * - column 2
 218        - field 2.1
 219        - :rspan:`1` :cspan:`1` field 2.2 - 3.3
 220
 221      * .. _`last row`:
 222
 223        - column 3
 224
 225
 226Including kernel-doc comments
 227=============================
 228
 229The Linux kernel source files may contain structured documentation comments, or
 230kernel-doc comments to describe the functions and types and design of the
 231code. The documentation comments may be included to any of the reStructuredText
 232documents using a dedicated kernel-doc Sphinx directive extension.
 233
 234The kernel-doc directive is of the format::
 235
 236  .. kernel-doc:: source
 237     :option:
 238
 239The *source* is the path to a source file, relative to the kernel source
 240tree. The following directive options are supported:
 241
 242export: *[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*.
 246
 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.
 250
 251  Examples::
 252
 253    .. kernel-doc:: lib/bitmap.c
 254       :export:
 255
 256    .. kernel-doc:: include/net/mac80211.h
 257       :export: net/mac80211/*.c
 258
 259internal: *[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*.
 263
 264  Example::
 265
 266    .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
 267       :internal:
 268
 269doc: *title*
 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.
 275
 276  Example::
 277
 278    .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
 279       :doc: High Definition Audio over HDMI and Display Port
 280
 281functions: *function* *[...]*
 282  Include documentation for each *function* in *source*.
 283
 284  Example::
 285
 286    .. kernel-doc:: lib/bitmap.c
 287       :functions: bitmap_parselist bitmap_parselist_user
 288
 289Without options, the kernel-doc directive includes all documentation comments
 290from the source file.
 291
 292The 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
 295source.
 296
 297.. _kernel_doc:
 298
 299Writing kernel-doc comments
 300===========================
 301
 302In order to provide embedded, "C" friendly, easy to maintain, but consistent and
 303extractable overview, function and type documentation, the Linux kernel has
 304adopted a consistent style for documentation comments. The format for this
 305documentation is called the kernel-doc format, described below. This style
 306embeds the documentation within the source files, using a few simple conventions
 307for adding documentation paragraphs and documenting functions and their
 308parameters, structures and unions and their members, enumerations, and typedefs.
 309
 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
 313   described here.
 314
 315The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
 316the documentation build to extract this embedded documentation into the various
 317HTML, PDF, and other format documents.
 318
 319In order to provide good documentation of kernel functions and data structures,
 320please use the following conventions to format your kernel-doc comments in the
 321Linux kernel source.
 322
 323How to format kernel-doc comments
 324---------------------------------
 325
 326The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
 327comments so marked will be considered by the ``kernel-doc`` tool. Use it only
 328for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
 329should be used as the closing comment marker. The lines in between should be
 330prefixed by `` * `` (space star space).
 331
 332The function and type kernel-doc comments should be placed just before the
 333function or type being described. The overview kernel-doc comments may be freely
 334placed at the top indentation level.
 335
 336Example kernel-doc function comment::
 337
 338  /**
 339   * foobar() - Brief description of foobar.
 340   * @arg: Description of argument of foobar.
 341   *
 342   * Longer description of foobar.
 343   *
 344   * Return: Description of return value of foobar.
 345   */
 346  int foobar(int arg)
 347
 348The format is similar for documentation for structures, enums, paragraphs,
 349etc. See the sections below for details.
 350
 351The kernel-doc structure is extracted from the comments, and proper `Sphinx C
 352Domain`_ function and type descriptions with anchors are generated for them. The
 353descriptions are filtered for special kernel-doc highlights and
 354cross-references. See below for details.
 355
 356.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
 357
 358Highlights and cross-references
 359-------------------------------
 360
 361The following special patterns are recognized in the kernel-doc comment
 362descriptive text and converted to proper reStructuredText markup and `Sphinx C
 363Domain`_ references.
 364
 365.. attention:: The below are **only** recognized within kernel-doc comments,
 366               **not** within normal reStructuredText documents.
 367
 368``funcname()``
 369  Function reference.
 370
 371``@parameter``
 372  Name of a function parameter. (No cross-referencing, just formatting.)
 373
 374``%CONST``
 375  Name of a constant. (No cross-referencing, just formatting.)
 376
 377``$ENVVAR``
 378  Name of an environment variable. (No cross-referencing, just formatting.)
 379
 380``&struct name``
 381  Structure reference.
 382
 383``&enum name``
 384  Enum reference.
 385
 386``&typedef name``
 387  Typedef reference.
 388
 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.
 392
 393``&name``
 394  A generic type reference. Prefer using the full reference described above
 395  instead. This is mostly for legacy comments.
 396
 397Cross-referencing from reStructuredText
 398~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 399
 400To cross-reference the functions and types defined in the kernel-doc comments
 401from reStructuredText documents, please use the `Sphinx C Domain`_
 402references. For example::
 403
 404  See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
 405
 406While the type reference works with just the type name, without the
 407struct/union/enum/typedef part in front, you may want to use::
 408
 409  See :c:type:`struct foo <foo>`.
 410  See :c:type:`union bar <bar>`.
 411  See :c:type:`enum baz <baz>`.
 412  See :c:type:`typedef meh <meh>`.
 413
 414This will produce prettier links, and is in line with how kernel-doc does the
 415cross-references.
 416
 417For further details, please refer to the `Sphinx C Domain`_ documentation.
 418
 419Function documentation
 420----------------------
 421
 422The general format of a function and function-like macro kernel-doc comment is::
 423
 424  /**
 425   * function_name() - Brief description of function.
 426   * @arg1: Describe the first argument.
 427   * @arg2: Describe the second argument.
 428   *        One can provide multiple line descriptions
 429   *        for arguments.
 430   *
 431   * A longer description, with more discussion of the function function_name()
 432   * that might be useful to those using or modifying it. Begins with an
 433   * empty comment line, and may include additional embedded empty
 434   * comment lines.
 435   *
 436   * The longer description may have multiple paragraphs.
 437   *
 438   * Return: Describe the return value of foobar.
 439   *
 440   * The return value description can also have multiple paragraphs, and should
 441   * be placed at the end of the comment block.
 442   */
 443
 444The brief description following the function name may span multiple lines, and
 445ends with an ``@argument:`` description, a blank comment line, or the end of the
 446comment block.
 447
 448The kernel-doc function comments describe each parameter to the function, in
 449order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
 450must begin on the very next line following the opening brief function
 451description line, with no intervening blank comment lines. The ``@argument:``
 452descriptions may span multiple lines. The continuation lines may contain
 453indentation. If a function parameter is ``...`` (varargs), it should be listed
 454in kernel-doc notation as: ``@...:``.
 455
 456The return value, if any, should be described in a dedicated section at the end
 457of the comment starting with "Return:".
 458
 459Structure, union, and enumeration documentation
 460-----------------------------------------------
 461
 462The general format of a struct, union, and enum kernel-doc comment is::
 463
 464  /**
 465   * struct struct_name - Brief description.
 466   * @member_name: Description of member member_name.
 467   *
 468   * Description of the structure.
 469   */
 470
 471Below, "struct" is used to mean structs, unions and enums, and "member" is used
 472to mean struct and union members as well as enumerations in an enum.
 473
 474The brief description following the structure name may span multiple lines, and
 475ends with a ``@member:`` description, a blank comment line, or the end of the
 476comment block.
 477
 478The kernel-doc data structure comments describe each member of the structure, in
 479order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
 480begin on the very next line following the opening brief function description
 481line, with no intervening blank comment lines. The ``@member:`` descriptions may
 482span multiple lines. The continuation lines may contain indentation.
 483
 484In-line member documentation comments
 485~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 486
 487The structure members may also be documented in-line within the definition::
 488
 489  /**
 490   * struct foo - Brief description.
 491   * @foo: The Foo member.
 492   */
 493  struct foo {
 494        int foo;
 495        /**
 496         * @bar: The Bar member.
 497         */
 498        int bar;
 499        /**
 500         * @baz: The Baz member.
 501         *
 502         * Here, the member description may contain several paragraphs.
 503         */
 504        int baz;
 505  }
 506
 507Private members
 508~~~~~~~~~~~~~~~
 509
 510Inside a struct description, you can use the "private:" and "public:" comment
 511tags. Structure fields that are inside a "private:" area are not listed in the
 512generated output documentation.  The "private:" and "public:" tags must begin
 513immediately following a ``/*`` comment marker.  They may optionally include
 514comments between the ``:`` and the ending ``*/`` marker.
 515
 516Example::
 517
 518  /**
 519   * struct my_struct - short description
 520   * @a: first member
 521   * @b: second member
 522   *
 523   * Longer description
 524   */
 525  struct my_struct {
 526      int a;
 527      int b;
 528  /* private: internal use only */
 529      int c;
 530  };
 531
 532
 533Typedef documentation
 534---------------------
 535
 536The general format of a typedef kernel-doc comment is::
 537
 538  /**
 539   * typedef type_name - Brief description.
 540   *
 541   * Description of the type.
 542   */
 543
 544Overview documentation comments
 545-------------------------------
 546
 547To facilitate having source code and comments close together, you can include
 548kernel-doc documentation blocks that are free-form comments instead of being
 549kernel-doc for functions, structures, unions, enums, or typedefs. This could be
 550used for something like a theory of operation for a driver or library code, for
 551example.
 552
 553This is done by using a ``DOC:`` section keyword with a section title.
 554
 555The general format of an overview or high-level documentation comment is::
 556
 557  /**
 558   * DOC: Theory of Operation
 559   *
 560   * The whizbang foobar is a dilly of a gizmo. It can do whatever you
 561   * want it to do, at any time. It reads your mind. Here's how it works.
 562   *
 563   * foo bar splat
 564   *
 565   * The only drawback to this gizmo is that is can sometimes damage
 566   * hardware, software, or its subject(s).
 567   */
 568
 569The title following ``DOC:`` acts as a heading within the source file, but also
 570as an identifier for extracting the documentation comment. Thus, the title must
 571be unique within the file.
 572
 573Recommendations
 574---------------
 575
 576We definitely need kernel-doc formatted documentation for functions that are
 577exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
 578
 579We also look to provide kernel-doc formatted documentation for functions
 580externally visible to other kernel files (not marked "static").
 581
 582We also recommend providing kernel-doc formatted documentation for private (file
 583"static") routines, for consistency of kernel source code layout. But this is
 584lower priority and at the discretion of the MAINTAINER of that kernel source
 585file.
 586
 587Data structures visible in kernel include files should also be documented using
 588kernel-doc formatted comments.
 589
 590DocBook XML [DEPRECATED]
 591========================
 592
 593.. attention::
 594
 595   This section describes the deprecated DocBook XML toolchain. Please do not
 596   create new DocBook XML template files. Please consider converting existing
 597   DocBook XML templates files to Sphinx/reStructuredText.
 598
 599Converting DocBook to Sphinx
 600----------------------------
 601
 602Over time, we expect all of the documents under ``Documentation/DocBook`` to be
 603converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
 604enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
 605which uses ``pandoc`` under the hood. For example::
 606
 607  $ cd Documentation/sphinx
 608  $ ./tmplcvt ../DocBook/in.tmpl ../out.rst
 609
 610Then edit the resulting rst files to fix any remaining issues, and add the
 611document in the ``toctree`` in ``Documentation/index.rst``.
 612
 613Components of the kernel-doc system
 614-----------------------------------
 615
 616Many places in the source tree have extractable documentation in the form of
 617block comments above functions. The components of this system are:
 618
 619- ``scripts/kernel-doc``
 620
 621  This is a perl script that hunts for the block comments and can mark them up
 622  directly into reStructuredText, DocBook, man, text, and HTML. (No, not
 623  texinfo.)
 624
 625- ``Documentation/DocBook/*.tmpl``
 626
 627  These are XML template files, which are normal XML files with special
 628  place-holders for where the extracted documentation should go.
 629
 630- ``scripts/docproc.c``
 631
 632  This is a program for converting XML template files into XML files. When a
 633  file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
 634  able to distinguish between internal and external functions.
 635
 636  It invokes kernel-doc, giving it the list of functions that are to be
 637  documented.
 638
 639  Additionally it is used to scan the XML template files to locate all the files
 640  referenced herein. This is used to generate dependency information as used by
 641  make.
 642
 643- ``Makefile``
 644
 645  The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
 646  DocBook XML files, PostScript files, PDF files, and html files in
 647  Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
 648
 649- ``Documentation/DocBook/Makefile``
 650
 651  This is where C files are associated with SGML templates.
 652
 653How to use kernel-doc comments in DocBook XML template files
 654------------------------------------------------------------
 655
 656DocBook XML template files (\*.tmpl) are like normal XML files, except that they
 657can contain escape sequences where extracted documentation should be inserted.
 658
 659``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
 660functions that are exported using ``EXPORT_SYMBOL``: the function list is
 661collected from files listed in ``Documentation/DocBook/Makefile``.
 662
 663``!I<filename>`` is replaced by the documentation for functions that are **not**
 664exported using ``EXPORT_SYMBOL``.
 665
 666``!D<filename>`` is used to name additional files to search for functions
 667exported using ``EXPORT_SYMBOL``.
 668
 669``!F<filename> <function [functions...]>`` is replaced by the documentation, in
 670``<filename>``, for the functions listed.
 671
 672``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
 673section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
 674``<section title>``; do not quote the ``<section title>``.
 675
 676``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
 677sections and documented functions, symbols, etc. are used. This makes sense to
 678use when you use ``!F`` or ``!P`` only and want to verify that all documentation
 679is included.
 680