Based on kernel version 4.9. Page generated on 2016-12-21 14:34 EST.
1 ========================== 2 Linux Kernel Documentation 3 ========================== 4 5 Introduction 6 ============ 7 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``. 12 13 .. _Sphinx: http://www.sphinx-doc.org/ 14 .. _reStructuredText: http://docutils.sourceforge.net/rst.html 15 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. 21 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 25 removed. 26 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. 30 31 Sphinx Build 32 ============ 33 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``. 38 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. 43 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 46 output. 47 48 To remove the generated documentation, run ``make cleandocs``. 49 50 Writing Documentation 51 ===================== 52 53 Adding new documentation can be as simple as: 54 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``. 57 58 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html 59 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 65 the main index. 66 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 70 markup 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 75 Specific guidelines for the kernel documentation 76 ------------------------------------------------ 77 78 Here 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 111 the C domain 112 ------------ 113 114 The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a 115 function prototype: 116 117 .. code-block:: rst 118 119 .. c:function:: int ioctl( int fd, int request ) 120 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 123 ``ioctl``: 124 125 .. code-block:: rst 126 127 .. c:function:: int ioctl( int fd, int request ) 128 :name: VIDIOC_LOG_STATUS 129 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: 133 134 .. code-block:: rst 135 136 :c:func:`VIDIOC_LOG_STATUS` 137 138 139 list tables 140 ----------- 141 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 144 comfortable for 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. 148 149 The ``flat-table`` is a double-stage list similar to the ``list-table`` with 150 some 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 163 options: 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 170 roles: 171 172 * ``:cspan:`` [int] additional columns (*morecols*) 173 * ``:rspan:`` [int] additional rows (*morerows*) 174 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 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 203 Rendered 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 226 Including kernel-doc comments 227 ============================= 228 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. 233 234 The kernel-doc directive is of the format:: 235 236 .. kernel-doc:: source 237 :option: 238 239 The *source* is the path to a source file, relative to the kernel source 240 tree. The following directive options are supported: 241 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*. 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 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*. 263 264 Example:: 265 266 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 267 :internal: 268 269 doc: *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 281 functions: *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 289 Without options, the kernel-doc directive includes all documentation comments 290 from the source file. 291 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 295 source. 296 297 .. _kernel_doc: 298 299 Writing kernel-doc comments 300 =========================== 301 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. 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 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. 318 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 321 Linux kernel source. 322 323 How to format kernel-doc comments 324 --------------------------------- 325 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). 331 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. 335 336 Example 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 348 The format is similar for documentation for structures, enums, paragraphs, 349 etc. See the sections below for details. 350 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. 355 356 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html 357 358 Highlights and cross-references 359 ------------------------------- 360 361 The following special patterns are recognized in the kernel-doc comment 362 descriptive text and converted to proper reStructuredText markup and `Sphinx C 363 Domain`_ 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 397 Cross-referencing from reStructuredText 398 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 399 400 To cross-reference the functions and types defined in the kernel-doc comments 401 from reStructuredText documents, please use the `Sphinx C Domain`_ 402 references. For example:: 403 404 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. 405 406 While the type reference works with just the type name, without the 407 struct/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 414 This will produce prettier links, and is in line with how kernel-doc does the 415 cross-references. 416 417 For further details, please refer to the `Sphinx C Domain`_ documentation. 418 419 Function documentation 420 ---------------------- 421 422 The 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 444 The brief description following the function name may span multiple lines, and 445 ends with an ``@argument:`` description, a blank comment line, or the end of the 446 comment block. 447 448 The kernel-doc function comments describe each parameter to the function, in 449 order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions 450 must begin on the very next line following the opening brief function 451 description line, with no intervening blank comment lines. The ``@argument:`` 452 descriptions may span multiple lines. The continuation lines may contain 453 indentation. If a function parameter is ``...`` (varargs), it should be listed 454 in kernel-doc notation as: ``@...:``. 455 456 The return value, if any, should be described in a dedicated section at the end 457 of the comment starting with "Return:". 458 459 Structure, union, and enumeration documentation 460 ----------------------------------------------- 461 462 The 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 471 Below, "struct" is used to mean structs, unions and enums, and "member" is used 472 to mean struct and union members as well as enumerations in an enum. 473 474 The brief description following the structure name may span multiple lines, and 475 ends with a ``@member:`` description, a blank comment line, or the end of the 476 comment block. 477 478 The kernel-doc data structure comments describe each member of the structure, in 479 order, with the ``@member:`` descriptions. The ``@member:`` descriptions must 480 begin on the very next line following the opening brief function description 481 line, with no intervening blank comment lines. The ``@member:`` descriptions may 482 span multiple lines. The continuation lines may contain indentation. 483 484 In-line member documentation comments 485 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 486 487 The 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 507 Private members 508 ~~~~~~~~~~~~~~~ 509 510 Inside a struct description, you can use the "private:" and "public:" comment 511 tags. Structure fields that are inside a "private:" area are not listed in the 512 generated output documentation. The "private:" and "public:" tags must begin 513 immediately following a ``/*`` comment marker. They may optionally include 514 comments between the ``:`` and the ending ``*/`` marker. 515 516 Example:: 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 533 Typedef documentation 534 --------------------- 535 536 The 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 544 Overview documentation comments 545 ------------------------------- 546 547 To facilitate having source code and comments close together, you can include 548 kernel-doc documentation blocks that are free-form comments instead of being 549 kernel-doc for functions, structures, unions, enums, or typedefs. This could be 550 used for something like a theory of operation for a driver or library code, for 551 example. 552 553 This is done by using a ``DOC:`` section keyword with a section title. 554 555 The 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 569 The title following ``DOC:`` acts as a heading within the source file, but also 570 as an identifier for extracting the documentation comment. Thus, the title must 571 be unique within the file. 572 573 Recommendations 574 --------------- 575 576 We definitely need kernel-doc formatted documentation for functions that are 577 exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. 578 579 We also look to provide kernel-doc formatted documentation for functions 580 externally visible to other kernel files (not marked "static"). 581 582 We also recommend providing kernel-doc formatted documentation for private (file 583 "static") routines, for consistency of kernel source code layout. But this is 584 lower priority and at the discretion of the MAINTAINER of that kernel source 585 file. 586 587 Data structures visible in kernel include files should also be documented using 588 kernel-doc formatted comments. 589 590 DocBook 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 599 Converting DocBook to Sphinx 600 ---------------------------- 601 602 Over time, we expect all of the documents under ``Documentation/DocBook`` to be 603 converted to Sphinx and reStructuredText. For most DocBook XML documents, a good 604 enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script, 605 which uses ``pandoc`` under the hood. For example:: 606 607 $ cd Documentation/sphinx 608 $ ./tmplcvt ../DocBook/in.tmpl ../out.rst 609 610 Then edit the resulting rst files to fix any remaining issues, and add the 611 document in the ``toctree`` in ``Documentation/index.rst``. 612 613 Components of the kernel-doc system 614 ----------------------------------- 615 616 Many places in the source tree have extractable documentation in the form of 617 block 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 653 How to use kernel-doc comments in DocBook XML template files 654 ------------------------------------------------------------ 655 656 DocBook XML template files (\*.tmpl) are like normal XML files, except that they 657 can contain escape sequences where extracted documentation should be inserted. 658 659 ``!E<filename>`` is replaced by the documentation, in ``<filename>``, for 660 functions that are exported using ``EXPORT_SYMBOL``: the function list is 661 collected from files listed in ``Documentation/DocBook/Makefile``. 662 663 ``!I<filename>`` is replaced by the documentation for functions that are **not** 664 exported using ``EXPORT_SYMBOL``. 665 666 ``!D<filename>`` is used to name additional files to search for functions 667 exported 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:`` 673 section 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: 677 sections and documented functions, symbols, etc. are used. This makes sense to 678 use when you use ``!F`` or ``!P`` only and want to verify that all documentation 679 is included.
