Lines Matching +full:in +full:- +full:kernel
1 .. title:: Kernel-doc comments
4 Writing kernel-doc comments
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
17 .. note:: kernel-doc does not cover Rust code: please see
18 Documentation/rust/general-information.rst instead.
20 The kernel-doc structure is extracted from the comments, and proper
22 generated from them. The descriptions are filtered for special kernel-doc
23 highlights and cross-references. See below for details.
25 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
28 ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
29 comment. Functions and data structures in header files which are intended
30 to be used by modules should also have kernel-doc comments.
32 It is good practice to also provide kernel-doc formatted documentation
33 for functions externally visible to other kernel files (not marked
34 ``static``). We also recommend providing kernel-doc formatted
36 kernel source code layout. This is lower priority and at the discretion
37 of the maintainer of that kernel source file.
39 How to format kernel-doc comments
40 ---------------------------------
42 The opening comment mark ``/**`` is used for kernel-doc comments. The
43 ``kernel-doc`` tool will extract comments marked this way. The rest of
44 the comment is formatted like a normal multi-line comment with a column
47 The function and type kernel-doc comments should be placed just before
48 the function or type being described in order to maximise the chance
50 overview kernel-doc comments may be placed anywhere at the top indentation
53 Running the ``kernel-doc`` tool with increased verbosity and without actual
57 scripts/kernel-doc -v -none drivers/foo/bar.c
59 The documentation format is verified by the kernel build when it is
65 ----------------------
67 The general format of a function and function-like macro kernel-doc comment is::
70 * function_name() - Brief description of function.
99 Each function argument should be described in order, immediately following
120 be written in kernel-doc notation as::
127 The context in which a function can be called should be described in a
139 * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
145 The return value, if any, should be described in a dedicated section
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::
154 * 0 - OK
155 * -EINVAL - invalid argument
156 * -ENOMEM - out of memory
160 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
162 So, in order to produce the desired line breaks, you need to use a
166 * * 0 - OK to runtime suspend the device
167 * * -EBUSY - Device should not be runtime suspended
175 -----------------------------------------------
177 The general format of a struct, union, and enum kernel-doc comment is::
180 * struct struct_name - Brief description.
189 You can replace the ``struct`` in the above example with ``union`` or
191 and union member names as well as enumerations in an enum.
202 and may be multi-line.
206 area are not listed in the generated output documentation.
215 * struct my_struct - short description
237 * struct nested_foobar - a struct with nested unions and structs
242 * @bar: non-anonymous union
279 #) When the nested struct/union is anonymous, the member ``bar`` in it
282 In-line member documentation comments
285 The structure members may also be documented in-line within the definition.
286 There are two styles, single-line comments where both the opening ``/**`` and
287 closing ``*/`` are on the same line, and multi-line comments where they are each
288 on a line of their own, like all other kernel-doc comments::
291 * struct foo - Brief description.
320 ---------------------
322 The general format of a typedef kernel-doc comment is::
325 * typedef type_name - Brief description.
333 * typedef type_name - Brief description.
344 Highlights and cross-references
345 -------------------------------
347 The following special patterns are recognized in the kernel-doc comment
351 .. attention:: The below are **only** recognized within kernel-doc comments,
358 Name of a function parameter. (No cross-referencing, just formatting.)
361 Name of a constant. (No cross-referencing, just formatting.)
364 A literal block that should be handled as-is. The output will use a
368 meaning either by kernel-doc script or by reStructuredText.
374 Name of an environment variable. (No cross-referencing, just formatting.)
385 ``&struct_name->member`` or ``&struct_name.member``
386 Structure or union member reference. The cross-reference will be to the struct
393 Cross-referencing from reStructuredText
396 No additional syntax is needed to cross-reference the functions and types
397 defined in the kernel-doc comments from reStructuredText documents.
408 However, if you want custom text in the cross-reference link, that can be done
417 -------------------------------
420 kernel-doc documentation blocks that are free-form comments instead of being
421 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
427 The general format of an overview or high-level documentation comment is::
446 Including kernel-doc comments
449 The documentation comments may be included in any of the reStructuredText
450 documents using a dedicated kernel-doc Sphinx directive extension.
452 The kernel-doc directive is of the format::
454 .. kernel-doc:: source
457 The *source* is the path to a source file, relative to the kernel source
460 export: *[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*.
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
471 .. kernel-doc:: lib/bitmap.c
474 .. kernel-doc:: include/net/mac80211.h
477 internal: *[source-pattern ...]*
478 Include documentation for all functions and types in *source* that have
480 in *source* or in any of the files specified by *source-pattern*.
484 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
488 Include documentation for each *function* and *type* in *source*.
490 and types in the *source* will be included.
494 .. kernel-doc:: lib/bitmap.c
497 .. kernel-doc:: lib/idr.c
500 no-identifiers: *[ function/type ...]*
501 Exclude documentation for each *function* and *type* in *source*.
505 .. kernel-doc:: lib/bitmap.c
506 :no-identifiers: bitmap_parselist
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
520 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
523 Without options, the kernel-doc directive includes all documentation comments
526 The kernel-doc extension is included in the kernel source tree, at
528 ``scripts/kernel-doc`` script to extract the documentation comments from the
533 How to use kernel-doc to generate man pages
534 -------------------------------------------
536 If you just want to use kernel-doc to generate man pages you can do this
537 from the kernel git tree::
539 $ scripts/kernel-doc -man \
540 $(git grep -l '/\*\*' -- :^Documentation :^tools) \
541 | scripts/split-man.pl /tmp/man
546 $ scripts/kernel-doc -man \
547 $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
548 | scripts/split-man.pl /tmp/man
550 $ scripts/kernel-doc -man \
551 $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
552 | scripts/split-man.pl /tmp/man