How to format kernel-doc comments¶

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

The function and type kernel-doc comments should be placed just before the function or type being described in order to maximise the chance that somebody changing the code will also change the documentation. The overview kernel-doc comments may be placed anywhere at the top indentation level.

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

tools/docs/kernel-doc -v -none drivers/foo/bar.c

The documentation format of .c files is also verified by the kernel build when it is requested to perform extra gcc checks:

make W=n

However, the above command does not verify header files. These should be checked separately using kernel-doc.

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, and ends with an argument description, a blank comment line, or the end of the comment 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 or enum to describe unions or enums. member is used to mean struct and union member names as well as enumerations in an enum.

The brief description following the structure name may span multiple lines, and ends with a member description, a blank comment line, or the end 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;
      /* private: hides memb2 from documentation */
      int memb2;
    };
    /* Everything here is public again, as private scope finished */
    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);

Variables documentation¶

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

/**
 * var var_name - Brief description.
 *
 * Description of the var_name variable.
 */
 extern int var_name;

Object-like macro documentation¶

Object-like macros are distinct from function-like macros. They are differentiated by whether the macro name is immediately followed by a left parenthesis (‘(’) for function-like macros or not followed by one for object-like macros.

Function-like macros are handled like functions by tools/docs/kernel-doc. They may have a parameter list. Object-like macros have do not have a parameter 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 comment descriptive text and converted to proper reStructuredText markup and Sphinx C Domain references.

funcname()

Function reference.

@parameter

Name of a function parameter, struct member, union member, or enum value. (No cross-referencing, just formatting.)

%CONST

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

Examples:

%0    %NULL    %-1    %-EFAULT    %-EINVAL    %-ENOMEM

``literal``

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

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

This is particularly useful if you need to use things like %ph inside a 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

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

&name

A generic type reference. Prefer using the full reference described above instead. 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 include kernel-doc documentation blocks that are free-form comments instead of being kernel-doc for functions, structures, unions, enums, typedefs or variables. This could be used for something like a theory of operation for a driver or library code, for example.

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 also as an identifier for extracting the documentation comment. Thus, the title must be unique within the file.

How to use kernel-doc to generate man pages¶

To generate man pages for all files that contain kernel-doc markups, run:

$ make mandocs

Or calling script-build-wrapper directly:

$ ./tools/docs/sphinx-build-wrapper mandocs

The output will be at /man directory inside the output directory (by default: Documentation/output).

Optionally, it is possible to generate a partial set of man pages by using SPHINXDIRS:

$ make SPHINXDIRS=driver-api/media mandocs