Lines Matching +full:non +full:- +full:descriptive
1 .. title:: Kernel-doc comments
4 Writing kernel-doc comments
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
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
30 to be used by modules should also have kernel-doc comments.
32 It is good practice to also provide kernel-doc formatted documentation
34 ``static``). We also recommend providing kernel-doc formatted
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
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
65 ----------------------
67 The general format of a function and function-like macro kernel-doc comment is::
70 * function_name() - Brief description of function.
120 be written in kernel-doc notation as::
139 * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
150 #) The multi-line descriptive text you provide does *not* recognize
154 * %0 - OK
155 * %-EINVAL - invalid argument
156 * %-ENOMEM - out of memory
160 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
166 * * %0 - OK to runtime suspend the device
167 * * %-EBUSY - Device should not be runtime suspended
169 #) If the descriptive text you provide has lines that begin with
175 -----------------------------------------------
177 The general format of a struct, union, and enum kernel-doc comment is::
180 * struct struct_name - Brief description.
202 and may be multi-line.
215 * struct my_struct - short description
237 * struct nested_foobar - a struct with nested unions and structs
242 * @bar: non-anonymous union
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 Object-like macro documentation
345 -------------------------------
347 Object-like macros are distinct from function-like macros. They are
349 left parenthesis ('(') for function-like macros or not followed by one
350 for object-like macros.
352 Function-like macros are handled like functions by ``scripts/kernel-doc``.
353 They may have a parameter list. Object-like macros have do not have a
356 The general format of an object-like macro kernel-doc comment is::
359 * define object_name - Brief description.
367 * define MAX_ERRNO - maximum errno value that is supported
378 * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \
389 Highlights and cross-references
390 -------------------------------
392 The following special patterns are recognized in the kernel-doc comment
393 descriptive text and converted to proper reStructuredText markup and `Sphinx C
396 .. attention:: The below are **only** recognized within kernel-doc comments,
403 Name of a function parameter. (No cross-referencing, just formatting.)
406 Name of a constant. (No cross-referencing, just formatting.)
409 A literal block that should be handled as-is. The output will use a
413 meaning either by kernel-doc script or by reStructuredText.
419 Name of an environment variable. (No cross-referencing, just formatting.)
430 ``&struct_name->member`` or ``&struct_name.member``
431 Structure or union member reference. The cross-reference will be to the struct
438 Cross-referencing from reStructuredText
441 No additional syntax is needed to cross-reference the functions and types
442 defined in the kernel-doc comments from reStructuredText documents.
453 However, if you want custom text in the cross-reference link, that can be done
462 -------------------------------
465 kernel-doc documentation blocks that are free-form comments instead of being
466 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
472 The general format of an overview or high-level documentation comment is::
491 Including kernel-doc comments
495 documents using a dedicated kernel-doc Sphinx directive extension.
497 The kernel-doc directive is of the format::
499 .. kernel-doc:: source
505 export: *[source-pattern ...]*
508 of the files specified by *source-pattern*.
510 The *source-pattern* is useful when the kernel-doc comments have been placed
516 .. kernel-doc:: lib/bitmap.c
519 .. kernel-doc:: include/net/mac80211.h
522 internal: *[source-pattern ...]*
525 in *source* or in any of the files specified by *source-pattern*.
529 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
539 .. kernel-doc:: lib/bitmap.c
542 .. kernel-doc:: lib/idr.c
545 no-identifiers: *[ function/type ...]*
550 .. kernel-doc:: lib/bitmap.c
551 :no-identifiers: bitmap_parselist
565 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
568 Without options, the kernel-doc directive includes all documentation comments
571 The kernel-doc extension is included in the kernel source tree, at
573 ``scripts/kernel-doc`` script to extract the documentation comments from the
578 How to use kernel-doc to generate man pages
579 -------------------------------------------
581 If you just want to use kernel-doc to generate man pages you can do this
584 $ scripts/kernel-doc -man \
585 $(git grep -l '/\*\*' -- :^Documentation :^tools) \
586 | scripts/split-man.pl /tmp/man
591 $ scripts/kernel-doc -man \
592 $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
593 | scripts/split-man.pl /tmp/man
595 $ scripts/kernel-doc -man \
596 $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
597 | scripts/split-man.pl /tmp/man