blob: 391decc66a18fd3da282cc009d6f239441de4a8d [file] [log] [blame]
Jani Nikula17defc22016-06-23 15:36:04 +03001==========================
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
Markus Heiser0249a762016-06-30 14:00:22 +0200110list tables
111-----------
112
113We recommend the use of *list table* formats. The *list table* formats are
114double-stage lists. Compared to the ASCII-art they might not be as
115comfortable for
116readers of the text files. Their advantage is that they are easy to
117create or modify and that the diff of a modification is much more meaningful,
118because it is limited to the modified content.
119
120The ``flat-table`` is a double-stage list similar to the ``list-table`` with
121some additional features:
122
123* column-span: with the role ``cspan`` a cell can be extended through
124 additional columns
125
126* row-span: with the role ``rspan`` a cell can be extended through
127 additional rows
128
129* auto span rightmost cell of a table row over the missing cells on the right
130 side of that table-row. With Option ``:fill-cells:`` this behavior can
131 changed from *auto span* to *auto fill*, which automatically inserts (empty)
132 cells instead of spanning the last cell.
133
134options:
135
136* ``:header-rows:`` [int] count of header rows
137* ``:stub-columns:`` [int] count of stub columns
138* ``:widths:`` [[int] [int] ... ] widths of columns
139* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
140
141roles:
142
143* ``:cspan:`` [int] additional columns (*morecols*)
144* ``:rspan:`` [int] additional rows (*morerows*)
145
146The example below shows how to use this markup. The first level of the staged
147list is the *table-row*. In the *table-row* there is only one markup allowed,
148the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
149and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
150<last row>`).
151
152.. code-block:: rst
153
154 .. flat-table:: table title
155 :widths: 2 1 1 3
156
157 * - head col 1
158 - head col 2
159 - head col 3
160 - head col 4
161
162 * - column 1
163 - field 1.1
164 - field 1.2 with autospan
165
166 * - column 2
167 - field 2.1
168 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
169
170 * .. _`last row`:
171
172 - column 3
173
174Rendered as:
175
176 .. flat-table:: table title
177 :widths: 2 1 1 3
178
179 * - head col 1
180 - head col 2
181 - head col 3
182 - head col 4
183
184 * - column 1
185 - field 1.1
186 - field 1.2 with autospan
187
188 * - column 2
189 - field 2.1
190 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
191
192 * .. _`last row`:
193
194 - column 3
195
Jani Nikula17defc22016-06-23 15:36:04 +0300196
197Including kernel-doc comments
198=============================
199
200The Linux kernel source files may contain structured documentation comments, or
201kernel-doc comments to describe the functions and types and design of the
202code. The documentation comments may be included to any of the reStructuredText
203documents using a dedicated kernel-doc Sphinx directive extension.
204
205The kernel-doc directive is of the format::
206
207 .. kernel-doc:: source
208 :option:
209
210The *source* is the path to a source file, relative to the kernel source
211tree. The following directive options are supported:
212
213export: *[source-pattern ...]*
214 Include documentation for all functions in *source* that have been exported
215 using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
216 of the files specified by *source-pattern*.
217
218 The *source-pattern* is useful when the kernel-doc comments have been placed
219 in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
220 the function definitions.
221
222 Examples::
223
224 .. kernel-doc:: lib/bitmap.c
225 :export:
226
227 .. kernel-doc:: include/net/mac80211.h
228 :export: net/mac80211/*.c
229
230internal: *[source-pattern ...]*
231 Include documentation for all functions and types in *source* that have
232 **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
233 in *source* or in any of the files specified by *source-pattern*.
234
235 Example::
236
237 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
238 :internal:
239
240doc: *title*
241 Include documentation for the ``DOC:`` paragraph identified by *title* in
242 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
243 is only used as an identifier for the paragraph, and is not included in the
244 output. Please make sure to have an appropriate heading in the enclosing
245 reStructuredText document.
246
247 Example::
248
249 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
250 :doc: High Definition Audio over HDMI and Display Port
251
252functions: *function* *[...]*
253 Include documentation for each *function* in *source*.
254
255 Example::
256
257 .. kernel-doc:: lib/bitmap.c
258 :functions: bitmap_parselist bitmap_parselist_user
259
260Without options, the kernel-doc directive includes all documentation comments
261from the source file.
262
263The kernel-doc extension is included in the kernel source tree, at
264``Documentation/sphinx/kernel-doc.py``. Internally, it uses the
265``scripts/kernel-doc`` script to extract the documentation comments from the
266source.
267
268Writing kernel-doc comments
269===========================
270
271In order to provide embedded, "C" friendly, easy to maintain, but consistent and
272extractable overview, function and type documentation, the Linux kernel has
273adopted a consistent style for documentation comments. The format for this
274documentation is called the kernel-doc format, described below. This style
275embeds the documentation within the source files, using a few simple conventions
276for adding documentation paragraphs and documenting functions and their
277parameters, structures and unions and their members, enumerations, and typedefs.
278
279.. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen,
280 yet distinctively different, for historical reasons. The kernel source
281 contains tens of thousands of kernel-doc comments. Please stick to the style
282 described here.
283
284The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
285the documentation build to extract this embedded documentation into the various
286HTML, PDF, and other format documents.
287
288In order to provide good documentation of kernel functions and data structures,
289please use the following conventions to format your kernel-doc comments in the
290Linux kernel source.
291
292How to format kernel-doc comments
293---------------------------------
294
295The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
296comments so marked will be considered by the ``kernel-doc`` tool. Use it only
297for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
298should be used as the closing comment marker. The lines in between should be
299prefixed by `` * `` (space star space).
300
301The function and type kernel-doc comments should be placed just before the
302function or type being described. The overview kernel-doc comments may be freely
303placed at the top indentation level.
304
305Example kernel-doc function comment::
306
307 /**
308 * foobar() - Brief description of foobar.
309 * @arg: Description of argument of foobar.
310 *
311 * Longer description of foobar.
312 *
313 * Return: Description of return value of foobar.
314 */
315 int foobar(int arg)
316
317The format is similar for documentation for structures, enums, paragraphs,
318etc. See the sections below for details.
319
320The kernel-doc structure is extracted from the comments, and proper `Sphinx C
321Domain`_ function and type descriptions with anchors are generated for them. The
322descriptions are filtered for special kernel-doc highlights and
323cross-references. See below for details.
324
325.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
326
327Highlights and cross-references
328-------------------------------
329
330The following special patterns are recognized in the kernel-doc comment
331descriptive text and converted to proper reStructuredText markup and `Sphinx C
332Domain`_ references.
333
334.. attention:: The below are **only** recognized within kernel-doc comments,
335 **not** within normal reStructuredText documents.
336
337``funcname()``
338 Function reference.
339
340``@parameter``
341 Name of a function parameter. (No cross-referencing, just formatting.)
342
343``%CONST``
344 Name of a constant. (No cross-referencing, just formatting.)
345
346``$ENVVAR``
347 Name of an environment variable. (No cross-referencing, just formatting.)
348
349``&struct name``
350 Structure reference.
351
352``&enum name``
353 Enum reference.
354
355``&typedef name``
356 Typedef reference.
357
358``&struct_name->member`` or ``&struct_name.member``
359 Structure or union member reference. The cross-reference will be to the struct
360 or union definition, not the member directly.
361
362``&name``
363 A generic type reference. Prefer using the full reference described above
364 instead. This is mostly for legacy comments.
365
366Cross-referencing from reStructuredText
367~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
368
369To cross-reference the functions and types defined in the kernel-doc comments
370from reStructuredText documents, please use the `Sphinx C Domain`_
371references. For example::
372
373 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
374
375While the type reference works with just the type name, without the
376struct/union/enum/typedef part in front, you may want to use::
377
378 See :c:type:`struct foo <foo>`.
379 See :c:type:`union bar <bar>`.
380 See :c:type:`enum baz <baz>`.
381 See :c:type:`typedef meh <meh>`.
382
383This will produce prettier links, and is in line with how kernel-doc does the
384cross-references.
385
386For further details, please refer to the `Sphinx C Domain`_ documentation.
387
388Function documentation
389----------------------
390
391The general format of a function and function-like macro kernel-doc comment is::
392
393 /**
394 * function_name() - Brief description of function.
395 * @arg1: Describe the first argument.
396 * @arg2: Describe the second argument.
397 * One can provide multiple line descriptions
398 * for arguments.
399 *
400 * A longer description, with more discussion of the function function_name()
401 * that might be useful to those using or modifying it. Begins with an
402 * empty comment line, and may include additional embedded empty
403 * comment lines.
404 *
405 * The longer description may have multiple paragraphs.
406 *
407 * Return: Describe the return value of foobar.
408 *
409 * The return value description can also have multiple paragraphs, and should
410 * be placed at the end of the comment block.
411 */
412
413The brief description following the function name may span multiple lines, and
414ends with an ``@argument:`` description, a blank comment line, or the end of the
415comment block.
416
417The kernel-doc function comments describe each parameter to the function, in
418order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
419must begin on the very next line following the opening brief function
420description line, with no intervening blank comment lines. The ``@argument:``
421descriptions may span multiple lines. The continuation lines may contain
422indentation. If a function parameter is ``...`` (varargs), it should be listed
423in kernel-doc notation as: ``@...:``.
424
425The return value, if any, should be described in a dedicated section at the end
426of the comment starting with "Return:".
427
428Structure, union, and enumeration documentation
429-----------------------------------------------
430
431The general format of a struct, union, and enum kernel-doc comment is::
432
433 /**
434 * struct struct_name - Brief description.
435 * @member_name: Description of member member_name.
436 *
437 * Description of the structure.
438 */
439
440Below, "struct" is used to mean structs, unions and enums, and "member" is used
441to mean struct and union members as well as enumerations in an enum.
442
443The brief description following the structure name may span multiple lines, and
444ends with a ``@member:`` description, a blank comment line, or the end of the
445comment block.
446
447The kernel-doc data structure comments describe each member of the structure, in
448order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
449begin on the very next line following the opening brief function description
450line, with no intervening blank comment lines. The ``@member:`` descriptions may
451span multiple lines. The continuation lines may contain indentation.
452
453In-line member documentation comments
454~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
455
456The structure members may also be documented in-line within the definition::
457
458 /**
459 * struct foo - Brief description.
460 * @foo: The Foo member.
461 */
462 struct foo {
463 int foo;
464 /**
465 * @bar: The Bar member.
466 */
467 int bar;
468 /**
469 * @baz: The Baz member.
470 *
471 * Here, the member description may contain several paragraphs.
472 */
473 int baz;
474 }
475
476Private members
477~~~~~~~~~~~~~~~
478
479Inside a struct description, you can use the "private:" and "public:" comment
480tags. Structure fields that are inside a "private:" area are not listed in the
481generated output documentation. The "private:" and "public:" tags must begin
482immediately following a ``/*`` comment marker. They may optionally include
483comments between the ``:`` and the ending ``*/`` marker.
484
485Example::
486
487 /**
488 * struct my_struct - short description
489 * @a: first member
490 * @b: second member
491 *
492 * Longer description
493 */
494 struct my_struct {
495 int a;
496 int b;
497 /* private: internal use only */
498 int c;
499 };
500
501
502Typedef documentation
503---------------------
504
505The general format of a typedef kernel-doc comment is::
506
507 /**
508 * typedef type_name - Brief description.
509 *
510 * Description of the type.
511 */
512
513Overview documentation comments
514-------------------------------
515
516To facilitate having source code and comments close together, you can include
517kernel-doc documentation blocks that are free-form comments instead of being
518kernel-doc for functions, structures, unions, enums, or typedefs. This could be
519used for something like a theory of operation for a driver or library code, for
520example.
521
522This is done by using a ``DOC:`` section keyword with a section title.
523
524The general format of an overview or high-level documentation comment is::
525
526 /**
527 * DOC: Theory of Operation
528 *
529 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
530 * want it to do, at any time. It reads your mind. Here's how it works.
531 *
532 * foo bar splat
533 *
534 * The only drawback to this gizmo is that is can sometimes damage
535 * hardware, software, or its subject(s).
536 */
537
538The title following ``DOC:`` acts as a heading within the source file, but also
539as an identifier for extracting the documentation comment. Thus, the title must
540be unique within the file.
541
542Recommendations
543---------------
544
545We definitely need kernel-doc formatted documentation for functions that are
546exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
547
548We also look to provide kernel-doc formatted documentation for functions
549externally visible to other kernel files (not marked "static").
550
551We also recommend providing kernel-doc formatted documentation for private (file
552"static") routines, for consistency of kernel source code layout. But this is
553lower priority and at the discretion of the MAINTAINER of that kernel source
554file.
555
556Data structures visible in kernel include files should also be documented using
557kernel-doc formatted comments.
558
559DocBook XML [DEPRECATED]
560========================
561
562.. attention::
563
564 This section describes the deprecated DocBook XML toolchain. Please do not
565 create new DocBook XML template files. Please consider converting existing
566 DocBook XML templates files to Sphinx/reStructuredText.
567
568Converting DocBook to Sphinx
569----------------------------
570
Jani Nikula17defc22016-06-23 15:36:04 +0300571Over time, we expect all of the documents under ``Documentation/DocBook`` to be
572converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
573enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
574which uses ``pandoc`` under the hood. For example::
575
576 $ cd Documentation/sphinx
577 $ ./tmplcvt ../DocBook/in.tmpl ../out.rst
578
579Then edit the resulting rst files to fix any remaining issues, and add the
580document in the ``toctree`` in ``Documentation/index.rst``.
581
582Components of the kernel-doc system
583-----------------------------------
584
585Many places in the source tree have extractable documentation in the form of
586block comments above functions. The components of this system are:
587
588- ``scripts/kernel-doc``
589
590 This is a perl script that hunts for the block comments and can mark them up
591 directly into reStructuredText, DocBook, man, text, and HTML. (No, not
592 texinfo.)
593
594- ``Documentation/DocBook/*.tmpl``
595
596 These are XML template files, which are normal XML files with special
597 place-holders for where the extracted documentation should go.
598
599- ``scripts/docproc.c``
600
601 This is a program for converting XML template files into XML files. When a
602 file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
603 able to distinguish between internal and external functions.
604
605 It invokes kernel-doc, giving it the list of functions that are to be
606 documented.
607
608 Additionally it is used to scan the XML template files to locate all the files
609 referenced herein. This is used to generate dependency information as used by
610 make.
611
612- ``Makefile``
613
614 The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
615 DocBook XML files, PostScript files, PDF files, and html files in
616 Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
617
618- ``Documentation/DocBook/Makefile``
619
620 This is where C files are associated with SGML templates.
621
622How to use kernel-doc comments in DocBook XML template files
623------------------------------------------------------------
624
625DocBook XML template files (\*.tmpl) are like normal XML files, except that they
626can contain escape sequences where extracted documentation should be inserted.
627
628``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
629functions that are exported using ``EXPORT_SYMBOL``: the function list is
630collected from files listed in ``Documentation/DocBook/Makefile``.
631
632``!I<filename>`` is replaced by the documentation for functions that are **not**
633exported using ``EXPORT_SYMBOL``.
634
635``!D<filename>`` is used to name additional files to search for functions
636exported using ``EXPORT_SYMBOL``.
637
638``!F<filename> <function [functions...]>`` is replaced by the documentation, in
639``<filename>``, for the functions listed.
640
641``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
642section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
643``<section title>``; do not quote the ``<section title>``.
644
645``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
646sections and documented functions, symbols, etc. are used. This makes sense to
647use when you use ``!F`` or ``!P`` only and want to verify that all documentation
648is included.