# kernel-doc コメントの書き方¶

The Linux kernel source files may contain structured documentation comments in the kernel-doc format to describe the functions, types and design of the code. It is easier to keep documentation up-to-date when it is embedded in source files.

The kernel-doc format is deceptively similar to javadoc, gtk-doc or Doxygen, yet distinctively different, for historical reasons. The kernel source contains tens of thousands of kernel-doc comments. Please stick to the style described here.

The kernel-doc structure is extracted from the comments, and proper Sphinx C Domain function and type descriptions with anchors are generated from them. The descriptions are filtered for special kernel-doc highlights and cross-references. See below for details.

Every function that is exported to loadable modules using EXPORT_SYMBOL or EXPORT_SYMBOL_GPL should have a kernel-doc comment. Functions and data structures in header files which are intended to be used by modules should also have kernel-doc comments.

It is good practice to also provide kernel-doc formatted documentation for functions externally visible to other kernel files (not marked static). We also recommend providing kernel-doc formatted documentation for private (file static) routines, for consistency of kernel source code layout. This is lower priority and at the discretion of the maintainer of that kernel source file.

## kernel-doc コメントのフォーマット¶

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:

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


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

make W=n


## 関数ドキュメント¶

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 foobar.
*
* 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.

### 関数パラメータ¶

Each function argument should be described in order, immediately following the short function description. Do not leave a blank line between the function description and the arguments, nor between the arguments.

Each @argument: description may span multiple lines.

If the @argument description has multiple lines, the continuation of the description should start at the same column as the previous line:

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


or:

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


If a function has a variable number of arguments, its description should be written in kernel-doc notation as:

* @...: description


### Function context¶

The context in which a function can be called should be described in a section named Context. This should include whether the function sleeps or can be called from interrupt context, as well as what locks it takes, releases and expects to be held by its caller.

Examples:

* 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.


### 返り値¶

The return value, if any, should be described in a dedicated section named Return.

1. The multi-line descriptive text you provide does not recognize line breaks, so if you try to format some text nicely, as in:

* Return:
* 0 - OK
* -EINVAL - invalid argument
* -ENOMEM - out of memory


this will all run together and produce:

Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory


So, in order to produce the desired line breaks, you need to use a ReST list, e. g.:

* Return:
* * 0             - OK to runtime suspend the device
* * -EBUSY        - Device should not be runtime suspended

2. If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which probably won't produce the desired effect.

## 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.

### Members¶

Members of structs, unions and enums should be documented the same way as function parameters; they immediately succeed the short description and may be multi-line.

Inside a struct or union description, you can use the private: and public: comment tags. Structure fields that are inside a private: area are not listed in the generated output documentation.

The private: and public: tags must begin immediately following a /* comment marker. They may optionally include comments between the : and the ending */ marker.

Example:

/**
* 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;
};


### Nested structs/unions¶

It is possible to document nested structs and unions, like:

/**
* 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;
};


1. When documenting nested structs or unions, if the struct/union foo is named, the member bar inside it should be documented as @foo.bar:
2. When the nested struct/union is anonymous, the member bar in it should be documented as @bar:

The structure members may also be documented in-line within the definition. There are two styles, single-line comments where both the opening /** and closing */ are on the same line, and multi-line comments where they are each on a line of their own, like all other kernel-doc comments:

/**
* 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.
* Return: Meaning of the return value.
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);


## 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.

The below are only recognized within kernel-doc comments, not within normal reStructuredText documents.

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 a monospaced font.

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

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