Lines Matching +full:non +full:- +full:descriptive
1 Writing kernel-doc comments
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
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
24 to be used by modules should also have kernel-doc comments.
26 It is good practice to also provide kernel-doc formatted documentation
28 ``static``). We also recommend providing kernel-doc formatted
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
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
59 ----------------------
61 The general format of a function and function-like macro kernel-doc comment is::
64 * function_name() - Brief description of function.
114 be written in kernel-doc notation as::
133 * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
144 #) The multi-line descriptive text you provide does *not* recognize
148 * 0 - OK
149 * -EINVAL - invalid argument
150 * -ENOMEM - out of memory
154 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
160 * * 0 - OK to runtime suspend the device
161 * * -EBUSY - Device should not be runtime suspended
163 #) If the descriptive text you provide has lines that begin with
169 -----------------------------------------------
171 The general format of a struct, union, and enum kernel-doc comment is::
174 * struct struct_name - Brief description.
196 and may be multi-line.
209 * struct my_struct - short description
231 * struct nested_foobar - a struct with nested unions and structs
236 * @bar: non-anonymous union
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
342 descriptive text and converted to proper reStructuredText markup and `Sphinx C
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
443 documents using a dedicated kernel-doc Sphinx directive extension.
445 The kernel-doc directive is of the format::
447 .. kernel-doc:: source
453 export: *[source-pattern ...]*
456 of the files specified by *source-pattern*.
458 The *source-pattern* is useful when the kernel-doc comments have been placed
464 .. kernel-doc:: lib/bitmap.c
467 .. kernel-doc:: include/net/mac80211.h
470 internal: *[source-pattern ...]*
473 in *source* or in any of the files specified by *source-pattern*.
477 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
487 .. kernel-doc:: lib/bitmap.c
490 .. kernel-doc:: lib/idr.c
493 no-identifiers: *[ function/type ...]*
498 .. kernel-doc:: lib/bitmap.c
499 :no-identifiers: bitmap_parselist
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
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