Lines Matching +full:in +full:- +full:kernel
1 Writing kernel-doc comments
4 The Linux kernel source files may contain structured documentation
5 comments in the kernel-doc format to describe the functions, types
6 and design of the code. It is easier to keep documentation up-to-date
7 when it is embedded in source files.
9 .. note:: The kernel-doc format is deceptively similar to javadoc,
10 gtk-doc or Doxygen, yet distinctively different, for historical
11 reasons. The kernel source contains tens of thousands of kernel-doc
14 The kernel-doc structure is extracted from the comments, and proper
16 generated from them. The descriptions are filtered for special kernel-doc
17 highlights and cross-references. See below for details.
19 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
22 ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
23 comment. Functions and data structures in header files which are intended
24 to be used by modules should also have kernel-doc comments.
26 It is good practice to also provide kernel-doc formatted documentation
27 for functions externally visible to other kernel files (not marked
28 ``static``). We also recommend providing kernel-doc formatted
30 kernel source code layout. This is lower priority and at the discretion
31 of the maintainer of that kernel source file.
33 How to format kernel-doc comments
34 ---------------------------------
36 The opening comment mark ``/**`` is used for kernel-doc comments. The
37 ``kernel-doc`` tool will extract comments marked this way. The rest of
38 the comment is formatted like a normal multi-line comment with a column
41 The function and type kernel-doc comments should be placed just before
42 the function or type being described in order to maximise the chance
44 overview kernel-doc comments may be placed anywhere at the top indentation
47 Running the ``kernel-doc`` tool with increased verbosity and without actual
51 scripts/kernel-doc -v -none drivers/foo/bar.c
53 The documentation format is verified by the kernel build when it is
59 ----------------------
61 The general format of a function and function-like macro kernel-doc comment is::
64 * function_name() - Brief description of function.
93 Each function argument should be described in order, immediately following
114 be written in kernel-doc notation as::
121 The context in which a function can be called should be described in a
133 * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
139 The return value, if any, should be described in a dedicated section
144 #) The multi-line descriptive text you provide does *not* recognize
145 line breaks, so if you try to format some text nicely, as in::
148 * 0 - OK
149 * -EINVAL - invalid argument
150 * -ENOMEM - out of memory
154 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
156 So, in order to produce the desired line breaks, you need to use a
160 * * 0 - OK to runtime suspend the device
161 * * -EBUSY - Device should not be runtime suspended
169 -----------------------------------------------
171 The general format of a struct, union, and enum kernel-doc comment is::
174 * struct struct_name - Brief description.
183 You can replace the ``struct`` in the above example with ``union`` or
185 and union member names as well as enumerations in an enum.
196 and may be multi-line.
200 area are not listed in the generated output documentation.
209 * struct my_struct - short description
231 * struct nested_foobar - a struct with nested unions and structs
236 * @bar: non-anonymous union
273 #) When the nested struct/union is anonymous, the member ``bar`` in it
276 In-line member documentation comments
279 The structure members may also be documented in-line within the definition.
280 There are two styles, single-line comments where both the opening ``/**`` and
281 closing ``*/`` are on the same line, and multi-line comments where they are each
282 on a line of their own, like all other kernel-doc comments::
285 * struct foo - Brief description.
314 ---------------------
316 The general format of a typedef kernel-doc comment is::
319 * typedef type_name - Brief description.
327 * typedef type_name - Brief description.
338 Highlights and cross-references
339 -------------------------------
341 The following special patterns are recognized in the kernel-doc comment
345 .. attention:: The below are **only** recognized within kernel-doc comments,
352 Name of a function parameter. (No cross-referencing, just formatting.)
355 Name of a constant. (No cross-referencing, just formatting.)
358 A literal block that should be handled as-is. The output will use a
362 meaning either by kernel-doc script or by reStructuredText.
368 Name of an environment variable. (No cross-referencing, just formatting.)
379 ``&struct_name->member`` or ``&struct_name.member``
380 Structure or union member reference. The cross-reference will be to the struct
387 Cross-referencing from reStructuredText
390 No additional syntax is needed to cross-reference the functions and types
391 defined in the kernel-doc comments from reStructuredText documents.
402 However, if you want custom text in the cross-reference link, that can be done
411 -------------------------------
414 kernel-doc documentation blocks that are free-form comments instead of being
415 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
421 The general format of an overview or high-level documentation comment is::
439 Including kernel-doc comments
442 The documentation comments may be included in any of the reStructuredText
443 documents using a dedicated kernel-doc Sphinx directive extension.
445 The kernel-doc directive is of the format::
447 .. kernel-doc:: source
450 The *source* is the path to a source file, relative to the kernel source
453 export: *[source-pattern ...]*
454 Include documentation for all functions in *source* that have been exported
455 using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
456 of the files specified by *source-pattern*.
458 The *source-pattern* is useful when the kernel-doc comments have been placed
459 in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
464 .. kernel-doc:: lib/bitmap.c
467 .. kernel-doc:: include/net/mac80211.h
470 internal: *[source-pattern ...]*
471 Include documentation for all functions and types in *source* that have
473 in *source* or in any of the files specified by *source-pattern*.
477 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
481 Include documentation for each *function* and *type* in *source*.
483 and types in the *source* will be included.
487 .. kernel-doc:: lib/bitmap.c
490 .. kernel-doc:: lib/idr.c
493 no-identifiers: *[ function/type ...]*
494 Exclude documentation for each *function* and *type* in *source*.
498 .. kernel-doc:: lib/bitmap.c
499 :no-identifiers: bitmap_parselist
505 Include documentation for the ``DOC:`` paragraph identified by *title* in
506 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
507 is only used as an identifier for the paragraph, and is not included in the
508 output. Please make sure to have an appropriate heading in the enclosing
513 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
516 Without options, the kernel-doc directive includes all documentation comments
519 The kernel-doc extension is included in the kernel source tree, at
521 ``scripts/kernel-doc`` script to extract the documentation comments from the
526 How to use kernel-doc to generate man pages
527 -------------------------------------------
529 If you just want to use kernel-doc to generate man pages you can do this
530 from the kernel git tree::
532 $ scripts/kernel-doc -man \
533 $(git grep -l '/\*\*' -- :^Documentation :^tools) \
534 | scripts/split-man.pl /tmp/man
539 $ scripts/kernel-doc -man \
540 $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
541 | scripts/split-man.pl /tmp/man
543 $ scripts/kernel-doc -man \
544 $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
545 | scripts/split-man.pl /tmp/man