1.. title:: Kernel-doc comments
2
3===========================
4Writing kernel-doc comments
5===========================
6
7The Linux kernel source files may contain structured documentation
8comments in the kernel-doc format to describe the functions, types
9and design of the code. It is easier to keep documentation up-to-date
10when it is embedded in source files.
11
12.. note:: The kernel-doc format is deceptively similar to javadoc,
13   gtk-doc or Doxygen, yet distinctively different, for historical
14   reasons. The kernel source contains tens of thousands of kernel-doc
15   comments. Please stick to the style described here.
16
17.. note:: kernel-doc does not cover Rust code: please see
18   Documentation/rust/general-information.rst instead.
19
20The kernel-doc structure is extracted from the comments, and proper
21`Sphinx C Domain`_ function and type descriptions with anchors are
22generated from them. The descriptions are filtered for special kernel-doc
23highlights and cross-references. See below for details.
24
25.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
26
27Every function that is exported to loadable modules using
28``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
29comment. Functions and data structures in header files which are intended
30to be used by modules should also have kernel-doc comments.
31
32It is good practice to also provide kernel-doc formatted documentation
33for functions externally visible to other kernel files (not marked
34``static``). We also recommend providing kernel-doc formatted
35documentation for private (file ``static``) routines, for consistency of
36kernel source code layout. This is lower priority and at the discretion
37of the maintainer of that kernel source file.
38
39How to format kernel-doc comments
40---------------------------------
41
42The opening comment mark ``/**`` is used for kernel-doc comments. The
43``kernel-doc`` tool will extract comments marked this way. The rest of
44the comment is formatted like a normal multi-line comment with a column
45of asterisks on the left side, closing with ``*/`` on a line by itself.
46
47The function and type kernel-doc comments should be placed just before
48the function or type being described in order to maximise the chance
49that somebody changing the code will also change the documentation. The
50overview kernel-doc comments may be placed anywhere at the top indentation
51level.
52
53Running the ``kernel-doc`` tool with increased verbosity and without actual
54output generation may be used to verify proper formatting of the
55documentation comments. For example::
56
57	scripts/kernel-doc -v -none drivers/foo/bar.c
58
59The documentation format is verified by the kernel build when it is
60requested to perform extra gcc checks::
61
62	make W=n
63
64Function documentation
65----------------------
66
67The general format of a function and function-like macro kernel-doc comment is::
68
69  /**
70   * function_name() - Brief description of function.
71   * @arg1: Describe the first argument.
72   * @arg2: Describe the second argument.
73   *        One can provide multiple line descriptions
74   *        for arguments.
75   *
76   * A longer description, with more discussion of the function function_name()
77   * that might be useful to those using or modifying it. Begins with an
78   * empty comment line, and may include additional embedded empty
79   * comment lines.
80   *
81   * The longer description may have multiple paragraphs.
82   *
83   * Context: Describes whether the function can sleep, what locks it takes,
84   *          releases, or expects to be held. It can extend over multiple
85   *          lines.
86   * Return: Describe the return value of function_name.
87   *
88   * The return value description can also have multiple paragraphs, and should
89   * be placed at the end of the comment block.
90   */
91
92The brief description following the function name may span multiple lines, and
93ends with an argument description, a blank comment line, or the end of the
94comment block.
95
96Function parameters
97~~~~~~~~~~~~~~~~~~~
98
99Each function argument should be described in order, immediately following
100the short function description.  Do not leave a blank line between the
101function description and the arguments, nor between the arguments.
102
103Each ``@argument:`` description may span multiple lines.
104
105.. note::
106
107   If the ``@argument`` description has multiple lines, the continuation
108   of the description should start at the same column as the previous line::
109
110      * @argument: some long description
111      *            that continues on next lines
112
113   or::
114
115      * @argument:
116      *		some long description
117      *		that continues on next lines
118
119If a function has a variable number of arguments, its description should
120be written in kernel-doc notation as::
121
122      * @...: description
123
124Function context
125~~~~~~~~~~~~~~~~
126
127The context in which a function can be called should be described in a
128section named ``Context``. This should include whether the function
129sleeps or can be called from interrupt context, as well as what locks
130it takes, releases and expects to be held by its caller.
131
132Examples::
133
134  * Context: Any context.
135  * Context: Any context. Takes and releases the RCU lock.
136  * Context: Any context. Expects <lock> to be held by caller.
137  * Context: Process context. May sleep if @gfp flags permit.
138  * Context: Process context. Takes and releases <mutex>.
139  * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
140  * Context: Interrupt context.
141
142Return values
143~~~~~~~~~~~~~
144
145The return value, if any, should be described in a dedicated section
146named ``Return``.
147
148.. note::
149
150  #) The multi-line descriptive text you provide does *not* recognize
151     line breaks, so if you try to format some text nicely, as in::
152
153	* Return:
154	* %0 - OK
155	* %-EINVAL - invalid argument
156	* %-ENOMEM - out of memory
157
158     this will all run together and produce::
159
160	Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
161
162     So, in order to produce the desired line breaks, you need to use a
163     ReST list, e. g.::
164
165      * Return:
166      * * %0		- OK to runtime suspend the device
167      * * %-EBUSY	- Device should not be runtime suspended
168
169  #) If the descriptive text you provide has lines that begin with
170     some phrase followed by a colon, each of those phrases will be taken
171     as a new section heading, which probably won't produce the desired
172     effect.
173
174Structure, union, and enumeration documentation
175-----------------------------------------------
176
177The general format of a struct, union, and enum kernel-doc comment is::
178
179  /**
180   * struct struct_name - Brief description.
181   * @member1: Description of member1.
182   * @member2: Description of member2.
183   *           One can provide multiple line descriptions
184   *           for members.
185   *
186   * Description of the structure.
187   */
188
189You can replace the ``struct`` in the above example with ``union`` or
190``enum``  to describe unions or enums. ``member`` is used to mean struct
191and union member names as well as enumerations in an enum.
192
193The brief description following the structure name may span multiple
194lines, and ends with a member description, a blank comment line, or the
195end of the comment block.
196
197Members
198~~~~~~~
199
200Members of structs, unions and enums should be documented the same way
201as function parameters; they immediately succeed the short description
202and may be multi-line.
203
204Inside a struct or union description, you can use the ``private:`` and
205``public:`` comment tags. Structure fields that are inside a ``private:``
206area are not listed in the generated output documentation.
207
208The ``private:`` and ``public:`` tags must begin immediately following a
209``/*`` comment marker. They may optionally include comments between the
210``:`` and the ending ``*/`` marker.
211
212Example::
213
214  /**
215   * struct my_struct - short description
216   * @a: first member
217   * @b: second member
218   * @d: fourth member
219   *
220   * Longer description
221   */
222  struct my_struct {
223      int a;
224      int b;
225  /* private: internal use only */
226      int c;
227  /* public: the next one is public */
228      int d;
229  };
230
231Nested structs/unions
232~~~~~~~~~~~~~~~~~~~~~
233
234It is possible to document nested structs and unions, like::
235
236      /**
237       * struct nested_foobar - a struct with nested unions and structs
238       * @memb1: first member of anonymous union/anonymous struct
239       * @memb2: second member of anonymous union/anonymous struct
240       * @memb3: third member of anonymous union/anonymous struct
241       * @memb4: fourth member of anonymous union/anonymous struct
242       * @bar: non-anonymous union
243       * @bar.st1: struct st1 inside @bar
244       * @bar.st2: struct st2 inside @bar
245       * @bar.st1.memb1: first member of struct st1 on union bar
246       * @bar.st1.memb2: second member of struct st1 on union bar
247       * @bar.st2.memb1: first member of struct st2 on union bar
248       * @bar.st2.memb2: second member of struct st2 on union bar
249       */
250      struct nested_foobar {
251        /* Anonymous union/struct*/
252        union {
253          struct {
254            int memb1;
255            int memb2;
256          };
257          struct {
258            void *memb3;
259            int memb4;
260          };
261        };
262        union {
263          struct {
264            int memb1;
265            int memb2;
266          } st1;
267          struct {
268            void *memb1;
269            int memb2;
270          } st2;
271        } bar;
272      };
273
274.. note::
275
276   #) When documenting nested structs or unions, if the struct/union ``foo``
277      is named, the member ``bar`` inside it should be documented as
278      ``@foo.bar:``
279   #) When the nested struct/union is anonymous, the member ``bar`` in it
280      should be documented as ``@bar:``
281
282In-line member documentation comments
283~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
284
285The structure members may also be documented in-line within the definition.
286There are two styles, single-line comments where both the opening ``/**`` and
287closing ``*/`` are on the same line, and multi-line comments where they are each
288on a line of their own, like all other kernel-doc comments::
289
290  /**
291   * struct foo - Brief description.
292   * @foo: The Foo member.
293   */
294  struct foo {
295        int foo;
296        /**
297         * @bar: The Bar member.
298         */
299        int bar;
300        /**
301         * @baz: The Baz member.
302         *
303         * Here, the member description may contain several paragraphs.
304         */
305        int baz;
306        union {
307                /** @foobar: Single line description. */
308                int foobar;
309        };
310        /** @bar2: Description for struct @bar2 inside @foo */
311        struct {
312                /**
313                 * @bar2.barbar: Description for @barbar inside @foo.bar2
314                 */
315                int barbar;
316        } bar2;
317  };
318
319Typedef documentation
320---------------------
321
322The general format of a typedef kernel-doc comment is::
323
324  /**
325   * typedef type_name - Brief description.
326   *
327   * Description of the type.
328   */
329
330Typedefs with function prototypes can also be documented::
331
332  /**
333   * typedef type_name - Brief description.
334   * @arg1: description of arg1
335   * @arg2: description of arg2
336   *
337   * Description of the type.
338   *
339   * Context: Locking context.
340   * Return: Meaning of the return value.
341   */
342   typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
343
344Highlights and cross-references
345-------------------------------
346
347The following special patterns are recognized in the kernel-doc comment
348descriptive text and converted to proper reStructuredText markup and `Sphinx C
349Domain`_ references.
350
351.. attention:: The below are **only** recognized within kernel-doc comments,
352	       **not** within normal reStructuredText documents.
353
354``funcname()``
355  Function reference.
356
357``@parameter``
358  Name of a function parameter. (No cross-referencing, just formatting.)
359
360``%CONST``
361  Name of a constant. (No cross-referencing, just formatting.)
362
363````literal````
364  A literal block that should be handled as-is. The output will use a
365  ``monospaced font``.
366
367  Useful if you need to use special characters that would otherwise have some
368  meaning either by kernel-doc script or by reStructuredText.
369
370  This is particularly useful if you need to use things like ``%ph`` inside
371  a function description.
372
373``$ENVVAR``
374  Name of an environment variable. (No cross-referencing, just formatting.)
375
376``&struct name``
377  Structure reference.
378
379``&enum name``
380  Enum reference.
381
382``&typedef name``
383  Typedef reference.
384
385``&struct_name->member`` or ``&struct_name.member``
386  Structure or union member reference. The cross-reference will be to the struct
387  or union definition, not the member directly.
388
389``&name``
390  A generic type reference. Prefer using the full reference described above
391  instead. This is mostly for legacy comments.
392
393Cross-referencing from reStructuredText
394~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
395
396No additional syntax is needed to cross-reference the functions and types
397defined in the kernel-doc comments from reStructuredText documents.
398Just end function names with ``()`` and write ``struct``, ``union``, ``enum``
399or ``typedef`` before types.
400For example::
401
402  See foo().
403  See struct foo.
404  See union bar.
405  See enum baz.
406  See typedef meh.
407
408However, if you want custom text in the cross-reference link, that can be done
409through the following syntax::
410
411  See :c:func:`my custom link text for function foo <foo>`.
412  See :c:type:`my custom link text for struct bar <bar>`.
413
414For further details, please refer to the `Sphinx C Domain`_ documentation.
415
416Overview documentation comments
417-------------------------------
418
419To facilitate having source code and comments close together, you can include
420kernel-doc documentation blocks that are free-form comments instead of being
421kernel-doc for functions, structures, unions, enums, or typedefs. This could be
422used for something like a theory of operation for a driver or library code, for
423example.
424
425This is done by using a ``DOC:`` section keyword with a section title.
426
427The general format of an overview or high-level documentation comment is::
428
429  /**
430   * DOC: Theory of Operation
431   *
432   * The whizbang foobar is a dilly of a gizmo. It can do whatever you
433   * want it to do, at any time. It reads your mind. Here's how it works.
434   *
435   * foo bar splat
436   *
437   * The only drawback to this gizmo is that is can sometimes damage
438   * hardware, software, or its subject(s).
439   */
440
441The title following ``DOC:`` acts as a heading within the source file, but also
442as an identifier for extracting the documentation comment. Thus, the title must
443be unique within the file.
444
445=============================
446Including kernel-doc comments
447=============================
448
449The documentation comments may be included in any of the reStructuredText
450documents using a dedicated kernel-doc Sphinx directive extension.
451
452The kernel-doc directive is of the format::
453
454  .. kernel-doc:: source
455     :option:
456
457The *source* is the path to a source file, relative to the kernel source
458tree. The following directive options are supported:
459
460export: *[source-pattern ...]*
461  Include documentation for all functions in *source* that have been exported
462  using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
463  of the files specified by *source-pattern*.
464
465  The *source-pattern* is useful when the kernel-doc comments have been placed
466  in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
467  the function definitions.
468
469  Examples::
470
471    .. kernel-doc:: lib/bitmap.c
472       :export:
473
474    .. kernel-doc:: include/net/mac80211.h
475       :export: net/mac80211/*.c
476
477internal: *[source-pattern ...]*
478  Include documentation for all functions and types in *source* that have
479  **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
480  in *source* or in any of the files specified by *source-pattern*.
481
482  Example::
483
484    .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
485       :internal:
486
487identifiers: *[ function/type ...]*
488  Include documentation for each *function* and *type* in *source*.
489  If no *function* is specified, the documentation for all functions
490  and types in the *source* will be included.
491
492  Examples::
493
494    .. kernel-doc:: lib/bitmap.c
495       :identifiers: bitmap_parselist bitmap_parselist_user
496
497    .. kernel-doc:: lib/idr.c
498       :identifiers:
499
500no-identifiers: *[ function/type ...]*
501  Exclude documentation for each *function* and *type* in *source*.
502
503  Example::
504
505    .. kernel-doc:: lib/bitmap.c
506       :no-identifiers: bitmap_parselist
507
508functions: *[ function/type ...]*
509  This is an alias of the 'identifiers' directive and deprecated.
510
511doc: *title*
512  Include documentation for the ``DOC:`` paragraph identified by *title* in
513  *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
514  is only used as an identifier for the paragraph, and is not included in the
515  output. Please make sure to have an appropriate heading in the enclosing
516  reStructuredText document.
517
518  Example::
519
520    .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
521       :doc: High Definition Audio over HDMI and Display Port
522
523Without options, the kernel-doc directive includes all documentation comments
524from the source file.
525
526The kernel-doc extension is included in the kernel source tree, at
527``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
528``scripts/kernel-doc`` script to extract the documentation comments from the
529source.
530
531.. _kernel_doc:
532
533How to use kernel-doc to generate man pages
534-------------------------------------------
535
536If you just want to use kernel-doc to generate man pages you can do this
537from the kernel git tree::
538
539  $ scripts/kernel-doc -man \
540    $(git grep -l '/\*\*' -- :^Documentation :^tools) \
541    | scripts/split-man.pl /tmp/man
542
543Some older versions of git do not support some of the variants of syntax for
544path exclusion.  One of the following commands may work for those versions::
545
546  $ scripts/kernel-doc -man \
547    $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
548    | scripts/split-man.pl /tmp/man
549
550  $ scripts/kernel-doc -man \
551    $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
552    | scripts/split-man.pl /tmp/man
553