About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / kernel-documentation.rst




Custom Search

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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.