Kernel-doc comments — The Linux Kernel documentation (2024)

How to format kernel-doc comments¶

The opening comment mark /** is used for kernel-doc comments. Thekernel-doc tool will extract comments marked this way. The rest ofthe comment is formatted like a normal multi-line comment with a columnof asterisks on the left side, closing with */ on a line by itself.

The function and type kernel-doc comments should be placed just beforethe function or type being described in order to maximise the chancethat somebody changing the code will also change the documentation. Theoverview kernel-doc comments may be placed anywhere at the top indentationlevel.

Running the kernel-doc tool with increased verbosity and without actualoutput generation may be used to verify proper formatting of thedocumentation comments. For example:

scripts/kernel-doc -v -none drivers/foo/bar.c

The documentation format is verified by the kernel build when it isrequested to perform extra gcc checks:

make W=n

Function documentation¶

The general format of a function and function-like macro kernel-doc comment is:

/** * function_name() - Brief description of function. * @arg1: Describe the first argument. * @arg2: Describe the second argument. * One can provide multiple line descriptions * for arguments. * * A longer description, with more discussion of the function function_name() * that might be useful to those using or modifying it. Begins with an * empty comment line, and may include additional embedded empty * comment lines. * * The longer description may have multiple paragraphs. * * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines. * Return: Describe the return value of function_name. * * The return value description can also have multiple paragraphs, and should * be placed at the end of the comment block. */

The brief description following the function name may span multiple lines, andends with an argument description, a blank comment line, or the end of thecomment block.

* @argument: some long description* that continues on next lines

* @argument:* some long description* that continues on next lines

* @...: description

* Context: Any context.* Context: Any context. Takes and releases the RCU lock.* Context: Any context. Expects <lock> to be held by caller.* Context: Process context. May sleep if @gfp flags permit.* Context: Process context. Takes and releases <mutex>.* Context: Softirq or process context. Takes and releases <lock>, BH-safe.* Context: Interrupt context.

Structure, union, and enumeration documentation¶

The general format of a struct, union, and enum kernel-doc comment is:

/** * struct struct_name - Brief description. * @member1: Description of member1. * @member2: Description of member2. * One can provide multiple line descriptions * for members. * * Description of the structure. */

You can replace the struct in the above example with union orenum to describe unions or enums. member is used to mean structand union member names as well as enumerations in an enum.

The brief description following the structure name may span multiplelines, and ends with a member description, a blank comment line, or theend of the comment block.

/** * struct my_struct - short description * @a: first member * @b: second member * @d: fourth member * * Longer description */struct my_struct { int a; int b;/* private: internal use only */ int c;/* public: the next one is public */ int d;};

/** * struct nested_foobar - a struct with nested unions and structs * @memb1: first member of anonymous union/anonymous struct * @memb2: second member of anonymous union/anonymous struct * @memb3: third member of anonymous union/anonymous struct * @memb4: fourth member of anonymous union/anonymous struct * @bar: non-anonymous union * @bar.st1: struct st1 inside @bar * @bar.st2: struct st2 inside @bar * @bar.st1.memb1: first member of struct st1 on union bar * @bar.st1.memb2: second member of struct st1 on union bar * @bar.st2.memb1: first member of struct st2 on union bar * @bar.st2.memb2: second member of struct st2 on union bar */struct nested_foobar { /* Anonymous union/struct*/ union { struct { int memb1; int memb2; }; struct { void *memb3; int memb4; }; }; union { struct { int memb1; int memb2; } st1; struct { void *memb1; int memb2; } st2; } bar;};

/** * struct foo - Brief description. * @foo: The Foo member. */struct foo { int foo; /** * @bar: The Bar member. */ int bar; /** * @baz: The Baz member. * * Here, the member description may contain several paragraphs. */ int baz; union { /** @foobar: Single line description. */ int foobar; }; /** @bar2: Description for struct @bar2 inside @foo */ struct { /** * @bar2.barbar: Description for @barbar inside @foo.bar2 */ int barbar; } bar2;};

Typedef documentation¶

The general format of a typedef kernel-doc comment is:

/** * typedef type_name - Brief description. * * Description of the type. */

Typedefs with function prototypes can also be documented:

/** * typedef type_name - Brief description. * @arg1: description of arg1 * @arg2: description of arg2 * * Description of the type. * * Context: Locking context. * Returns: Meaning of the return value. */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);

Object-like macro documentation¶

Object-like macros are distinct from function-like macros. They aredifferentiated by whether the macro name is immediately followed by aleft parenthesis (‘(’) for function-like macros or not followed by onefor object-like macros.

Function-like macros are handled like functions by scripts/kernel-doc.They may have a parameter list. Object-like macros have do not have aparameter list.

The general format of an object-like macro kernel-doc comment is:

/** * define object_name - Brief description. * * Description of the object. */

Example:

/** * define MAX_ERRNO - maximum errno value that is supported * * Kernel pointers have redundant information, so we can use a * scheme where we can return either an error code or a normal * pointer with the same return value. */#define MAX_ERRNO 4095

Example:

/** * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ * Initializes struct drm_plane_helper_funcs for VRAM handling * * This macro initializes struct drm_plane_helper_funcs to use the * respective helper functions. */#define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \ .prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \ .cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb

Highlights and cross-references¶

The following special patterns are recognized in the kernel-doc commentdescriptive text and converted to proper reStructuredText markup and Sphinx CDomain references.

funcname()

Function reference.

@parameter

Name of a function parameter. (No cross-referencing, just formatting.)

%CONST

Name of a constant. (No cross-referencing, just formatting.)

``literal``

A literal block that should be handled as-is. The output will use amonospaced font.

Useful if you need to use special characters that would otherwise have somemeaning either by kernel-doc script or by reStructuredText.

This is particularly useful if you need to use things like %ph insidea function description.

$ENVVAR

Name of an environment variable. (No cross-referencing, just formatting.)

&struct name

Structure reference.

&enum name

Enum reference.

&typedef name

Typedef reference.

&struct_name->member or &struct_name.member

Structure or union member reference. The cross-reference will be to the structor union definition, not the member directly.

&name

A generic type reference. Prefer using the full reference described aboveinstead. This is mostly for legacy comments.

See foo().See struct foo.See union bar.See enum baz.See typedef meh.

See :c:func:`my custom link text for function foo <foo>`.See :c:type:`my custom link text for struct bar <bar>`.

Overview documentation comments¶

To facilitate having source code and comments close together, you can includekernel-doc documentation blocks that are free-form comments instead of beingkernel-doc for functions, structures, unions, enums, or typedefs. This could beused for something like a theory of operation for a driver or library code, forexample.

This is done by using a DOC: section keyword with a section title.

The general format of an overview or high-level documentation comment is:

/** * DOC: Theory of Operation * * The whizbang foobar is a dilly of a gizmo. It can do whatever you * want it to do, at any time. It reads your mind. Here's how it works. * * foo bar splat * * The only drawback to this gizmo is that is can sometimes damage * hardware, software, or its subject(s). */

The title following DOC: acts as a heading within the source file, but alsoas an identifier for extracting the documentation comment. Thus, the title mustbe unique within the file.

How to use kernel-doc to generate man pages¶

If you just want to use kernel-doc to generate man pages you can do thisfrom the kernel git tree:

$ scripts/kernel-doc -man \ $(git grep -l '/\*\*' -- :^Documentation :^tools) \ | scripts/split-man.pl /tmp/man

Some older versions of git do not support some of the variants of syntax forpath exclusion. One of the following commands may work for those versions:

$ scripts/kernel-doc -man \ $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ | scripts/split-man.pl /tmp/man$ scripts/kernel-doc -man \ $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ | scripts/split-man.pl /tmp/man