1 .. title:: Kernel-doc comments
3 ===========================
4 Writing kernel-doc comments
5 ===========================
7 The Linux kernel source files may contain structured documentation
8 comments in the kernel-doc format to describe the functions, types
9 and design of the code. It is easier to keep documentation up-to-date
10 when it is embedded in source files.
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.
17 The kernel-doc structure is extracted from the comments, and proper
18 `Sphinx C Domain`_ function and type descriptions with anchors are
19 generated from them. The descriptions are filtered for special kernel-doc
20 highlights and cross-references. See below for details.
22 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
24 Every function that is exported to loadable modules using
25 ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
26 comment. Functions and data structures in header files which are intended
27 to be used by modules should also have kernel-doc comments.
29 It is good practice to also provide kernel-doc formatted documentation
30 for functions externally visible to other kernel files (not marked
31 ``static``). We also recommend providing kernel-doc formatted
32 documentation for private (file ``static``) routines, for consistency of
33 kernel source code layout. This is lower priority and at the discretion
34 of the maintainer of that kernel source file.
36 How to format kernel-doc comments
37 ---------------------------------
39 The opening comment mark ``/**`` is used for kernel-doc comments. The
40 ``kernel-doc`` tool will extract comments marked this way. The rest of
41 the comment is formatted like a normal multi-line comment with a column
42 of asterisks on the left side, closing with ``*/`` on a line by itself.
44 The function and type kernel-doc comments should be placed just before
45 the function or type being described in order to maximise the chance
46 that somebody changing the code will also change the documentation. The
47 overview kernel-doc comments may be placed anywhere at the top indentation
50 Running the ``kernel-doc`` tool with increased verbosity and without actual
51 output generation may be used to verify proper formatting of the
52 documentation comments. For example::
54 scripts/kernel-doc -v -none drivers/foo/bar.c
56 The documentation format is verified by the kernel build when it is
57 requested to perform extra gcc checks::
61 Function documentation
62 ----------------------
64 The general format of a function and function-like macro kernel-doc comment is::
67 * function_name() - Brief description of function.
68 * @arg1: Describe the first argument.
69 * @arg2: Describe the second argument.
70 * One can provide multiple line descriptions
73 * A longer description, with more discussion of the function function_name()
74 * that might be useful to those using or modifying it. Begins with an
75 * empty comment line, and may include additional embedded empty
78 * The longer description may have multiple paragraphs.
80 * Context: Describes whether the function can sleep, what locks it takes,
81 * releases, or expects to be held. It can extend over multiple
83 * Return: Describe the return value of function_name.
85 * The return value description can also have multiple paragraphs, and should
86 * be placed at the end of the comment block.
89 The brief description following the function name may span multiple lines, and
90 ends with an argument description, a blank comment line, or the end of the
96 Each function argument should be described in order, immediately following
97 the short function description. Do not leave a blank line between the
98 function description and the arguments, nor between the arguments.
100 Each ``@argument:`` description may span multiple lines.
104 If the ``@argument`` description has multiple lines, the continuation
105 of the description should start at the same column as the previous line::
107 * @argument: some long description
108 * that continues on next lines
113 * some long description
114 * that continues on next lines
116 If a function has a variable number of arguments, its description should
117 be written in kernel-doc notation as::
124 The context in which a function can be called should be described in a
125 section named ``Context``. This should include whether the function
126 sleeps or can be called from interrupt context, as well as what locks
127 it takes, releases and expects to be held by its caller.
131 * Context: Any context.
132 * Context: Any context. Takes and releases the RCU lock.
133 * Context: Any context. Expects <lock> to be held by caller.
134 * Context: Process context. May sleep if @gfp flags permit.
135 * Context: Process context. Takes and releases <mutex>.
136 * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
137 * Context: Interrupt context.
142 The return value, if any, should be described in a dedicated section
147 #) The multi-line descriptive text you provide does *not* recognize
148 line breaks, so if you try to format some text nicely, as in::
152 * -EINVAL - invalid argument
153 * -ENOMEM - out of memory
155 this will all run together and produce::
157 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
159 So, in order to produce the desired line breaks, you need to use a
163 * * 0 - OK to runtime suspend the device
164 * * -EBUSY - Device should not be runtime suspended
166 #) If the descriptive text you provide has lines that begin with
167 some phrase followed by a colon, each of those phrases will be taken
168 as a new section heading, which probably won't produce the desired
171 Structure, union, and enumeration documentation
172 -----------------------------------------------
174 The general format of a struct, union, and enum kernel-doc comment is::
177 * struct struct_name - Brief description.
178 * @member1: Description of member1.
179 * @member2: Description of member2.
180 * One can provide multiple line descriptions
183 * Description of the structure.
186 You can replace the ``struct`` in the above example with ``union`` or
187 ``enum`` to describe unions or enums. ``member`` is used to mean struct
188 and union member names as well as enumerations in an enum.
190 The brief description following the structure name may span multiple
191 lines, and ends with a member description, a blank comment line, or the
192 end of the comment block.
197 Members of structs, unions and enums should be documented the same way
198 as function parameters; they immediately succeed the short description
199 and may be multi-line.
201 Inside a struct or union description, you can use the ``private:`` and
202 ``public:`` comment tags. Structure fields that are inside a ``private:``
203 area are not listed in the generated output documentation.
205 The ``private:`` and ``public:`` tags must begin immediately following a
206 ``/*`` comment marker. They may optionally include comments between the
207 ``:`` and the ending ``*/`` marker.
212 * struct my_struct - short description
222 /* private: internal use only */
224 /* public: the next one is public */
228 Nested structs/unions
229 ~~~~~~~~~~~~~~~~~~~~~
231 It is possible to document nested structs and unions, like::
234 * struct nested_foobar - a struct with nested unions and structs
235 * @memb1: first member of anonymous union/anonymous struct
236 * @memb2: second member of anonymous union/anonymous struct
237 * @memb3: third member of anonymous union/anonymous struct
238 * @memb4: fourth member of anonymous union/anonymous struct
239 * @bar: non-anonymous union
240 * @bar.st1: struct st1 inside @bar
241 * @bar.st2: struct st2 inside @bar
242 * @bar.st1.memb1: first member of struct st1 on union bar
243 * @bar.st1.memb2: second member of struct st1 on union bar
244 * @bar.st2.memb1: first member of struct st2 on union bar
245 * @bar.st2.memb2: second member of struct st2 on union bar
247 struct nested_foobar {
248 /* Anonymous union/struct*/
273 #) When documenting nested structs or unions, if the struct/union ``foo``
274 is named, the member ``bar`` inside it should be documented as
276 #) When the nested struct/union is anonymous, the member ``bar`` in it
277 should be documented as ``@bar:``
279 In-line member documentation comments
280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
282 The structure members may also be documented in-line within the definition.
283 There are two styles, single-line comments where both the opening ``/**`` and
284 closing ``*/`` are on the same line, and multi-line comments where they are each
285 on a line of their own, like all other kernel-doc comments::
288 * struct foo - Brief description.
289 * @foo: The Foo member.
294 * @bar: The Bar member.
298 * @baz: The Baz member.
300 * Here, the member description may contain several paragraphs.
304 /** @foobar: Single line description. */
307 /** @bar2: Description for struct @bar2 inside @foo */
310 * @bar2.barbar: Description for @barbar inside @foo.bar2
316 Typedef documentation
317 ---------------------
319 The general format of a typedef kernel-doc comment is::
322 * typedef type_name - Brief description.
324 * Description of the type.
327 Typedefs with function prototypes can also be documented::
330 * typedef type_name - Brief description.
331 * @arg1: description of arg1
332 * @arg2: description of arg2
334 * Description of the type.
336 * Context: Locking context.
337 * Return: Meaning of the return value.
339 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
341 Highlights and cross-references
342 -------------------------------
344 The following special patterns are recognized in the kernel-doc comment
345 descriptive text and converted to proper reStructuredText markup and `Sphinx C
348 .. attention:: The below are **only** recognized within kernel-doc comments,
349 **not** within normal reStructuredText documents.
355 Name of a function parameter. (No cross-referencing, just formatting.)
358 Name of a constant. (No cross-referencing, just formatting.)
361 A literal block that should be handled as-is. The output will use a
364 Useful if you need to use special characters that would otherwise have some
365 meaning either by kernel-doc script or by reStructuredText.
367 This is particularly useful if you need to use things like ``%ph`` inside
368 a function description.
371 Name of an environment variable. (No cross-referencing, just formatting.)
382 ``&struct_name->member`` or ``&struct_name.member``
383 Structure or union member reference. The cross-reference will be to the struct
384 or union definition, not the member directly.
387 A generic type reference. Prefer using the full reference described above
388 instead. This is mostly for legacy comments.
390 Cross-referencing from reStructuredText
391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
393 No additional syntax is needed to cross-reference the functions and types
394 defined in the kernel-doc comments from reStructuredText documents.
395 Just end function names with ``()`` and write ``struct``, ``union``, ``enum``
396 or ``typedef`` before types.
405 However, if you want custom text in the cross-reference link, that can be done
406 through the following syntax::
408 See :c:func:`my custom link text for function foo <foo>`.
409 See :c:type:`my custom link text for struct bar <bar>`.
411 For further details, please refer to the `Sphinx C Domain`_ documentation.
413 Overview documentation comments
414 -------------------------------
416 To facilitate having source code and comments close together, you can include
417 kernel-doc documentation blocks that are free-form comments instead of being
418 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
419 used for something like a theory of operation for a driver or library code, for
422 This is done by using a ``DOC:`` section keyword with a section title.
424 The general format of an overview or high-level documentation comment is::
427 * DOC: Theory of Operation
429 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
430 * want it to do, at any time. It reads your mind. Here's how it works.
434 * The only drawback to this gizmo is that is can sometimes damage
435 * hardware, software, or its subject(s).
438 The title following ``DOC:`` acts as a heading within the source file, but also
439 as an identifier for extracting the documentation comment. Thus, the title must
440 be unique within the file.
442 =============================
443 Including kernel-doc comments
444 =============================
446 The documentation comments may be included in any of the reStructuredText
447 documents using a dedicated kernel-doc Sphinx directive extension.
449 The kernel-doc directive is of the format::
451 .. kernel-doc:: source
454 The *source* is the path to a source file, relative to the kernel source
455 tree. The following directive options are supported:
457 export: *[source-pattern ...]*
458 Include documentation for all functions in *source* that have been exported
459 using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
460 of the files specified by *source-pattern*.
462 The *source-pattern* is useful when the kernel-doc comments have been placed
463 in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
464 the function definitions.
468 .. kernel-doc:: lib/bitmap.c
471 .. kernel-doc:: include/net/mac80211.h
472 :export: net/mac80211/*.c
474 internal: *[source-pattern ...]*
475 Include documentation for all functions and types in *source* that have
476 **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
477 in *source* or in any of the files specified by *source-pattern*.
481 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
484 identifiers: *[ function/type ...]*
485 Include documentation for each *function* and *type* in *source*.
486 If no *function* is specified, the documentation for all functions
487 and types in the *source* will be included.
491 .. kernel-doc:: lib/bitmap.c
492 :identifiers: bitmap_parselist bitmap_parselist_user
494 .. kernel-doc:: lib/idr.c
497 no-identifiers: *[ function/type ...]*
498 Exclude documentation for each *function* and *type* in *source*.
502 .. kernel-doc:: lib/bitmap.c
503 :no-identifiers: bitmap_parselist
505 functions: *[ function/type ...]*
506 This is an alias of the 'identifiers' directive and deprecated.
509 Include documentation for the ``DOC:`` paragraph identified by *title* in
510 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
511 is only used as an identifier for the paragraph, and is not included in the
512 output. Please make sure to have an appropriate heading in the enclosing
513 reStructuredText document.
517 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
518 :doc: High Definition Audio over HDMI and Display Port
520 Without options, the kernel-doc directive includes all documentation comments
521 from the source file.
523 The kernel-doc extension is included in the kernel source tree, at
524 ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
525 ``scripts/kernel-doc`` script to extract the documentation comments from the
530 How to use kernel-doc to generate man pages
531 -------------------------------------------
533 If you just want to use kernel-doc to generate man pages you can do this
534 from the kernel git tree::
536 $ scripts/kernel-doc -man \
537 $(git grep -l '/\*\*' -- :^Documentation :^tools) \
538 | scripts/split-man.pl /tmp/man
540 Some older versions of git do not support some of the variants of syntax for
541 path exclusion. One of the following commands may work for those versions::
543 $ scripts/kernel-doc -man \
544 $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
545 | scripts/split-man.pl /tmp/man
547 $ scripts/kernel-doc -man \
548 $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
549 | scripts/split-man.pl /tmp/man