Lines Matching +full:foo +full:- +full:bar
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
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
243 * @bar.st1: struct st1 inside @bar
244 * @bar.st2: struct st2 inside @bar
245 * @bar.st1.memb1: first member of struct st1 on union bar
246 * @bar.st1.memb2: second member of struct st1 on union bar
247 * @bar.st2.memb1: first member of struct st2 on union bar
248 * @bar.st2.memb2: second member of struct st2 on union bar
271 } bar;
276 #) When documenting nested structs or unions, if the struct/union ``foo``
277 is named, the member ``bar`` inside it should be documented as
278 ``@foo.bar:``
279 #) When the nested struct/union is anonymous, the member ``bar`` in it
280 should be documented as ``@bar:``
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.
292 * @foo: The Foo member.
294 struct foo {
295 int foo;
297 * @bar: The Bar member.
299 int bar;
310 /** @bar2: Description for struct @bar2 inside @foo */
313 * @bar2.barbar: Description for @barbar inside @foo.bar2
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.
402 See foo().
403 See struct foo.
404 See union bar.
408 However, if you want custom text in the cross-reference link, that can be done
411 See :c:func:`my custom link text for function foo <foo>`.
412 See :c:type:`my custom link text for struct bar <bar>`.
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::
435 * foo bar splat
446 Including kernel-doc comments
450 documents using a dedicated kernel-doc Sphinx directive extension.
452 The kernel-doc directive is of the format::
454 .. kernel-doc:: source
460 export: *[source-pattern ...]*
463 of the files specified by *source-pattern*.
465 The *source-pattern* is useful when the kernel-doc comments have been placed
471 .. kernel-doc:: lib/bitmap.c
474 .. kernel-doc:: include/net/mac80211.h
477 internal: *[source-pattern ...]*
480 in *source* or in any of the files specified by *source-pattern*.
484 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
494 .. kernel-doc:: lib/bitmap.c
497 .. kernel-doc:: lib/idr.c
500 no-identifiers: *[ function/type ...]*
505 .. kernel-doc:: lib/bitmap.c
506 :no-identifiers: bitmap_parselist
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
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