Skip to content

L
linux
Commit 46347502 authored by Matthew Wilcox's avatar Matthew Wilcox Committed by Jonathan Corbet
Browse files
Options

Restructure kernel-doc.rst 

I found the layout confusing with multiple introductions to what
kernel-doc is and how to use it.

I made the following changes:
 - Moved the 'Including kernel-doc comments' section to the end of
   the document -- we should explain what it *is* before we explain
   how to integrate it.
 - Moved the 'Recommendations' subsection to the top.  We want people
   to know what to document before telling them how to do it.
 - Rewrite the 'Writing kernel-doc comments' section, integrating
   the 'Recommendations' subsection and a paragraph from 'How to format
   kernel-doc comments'.
 - Remove the paragraph about the kernel-doc script; we're supposed to
   be teaching people how to use punctuation to write pretty documentation,
   not documenting the build tooling.
 - Split the 'Parameters and member arguments' section into 'Function
   parameters' and 'Members'.  Structure members are not commonly
   referred to as arguments.
 - Integrate the 'private:' and 'public:' tag descriptions into the
   'Members' section.
 - Move the 'In-line member documentation comments' subsection up to be
   with the 'Members' section.
Signed-off-by: default avatarMatthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 9831e554
Show whitespace changes
Inline Side-by-side
Showing with 217 additions and 259 deletions
Documentation/doc-guide/kernel-doc.rst
View file @ 46347502
Including kernel-doc comments
=============================
The Linux kernel source files may contain structured documentation comments, or
kernel-doc comments to describe the functions and types and design of the
code. The documentation comments may be included to any of the reStructuredText
documents using a dedicated kernel-doc Sphinx directive extension.
The kernel-doc directive is of the format::
.. kernel-doc:: source
:option:
The *source* is the path to a source file, relative to the kernel source
tree. The following directive options are supported:
export: *[source-pattern ...]*
Include documentation for all functions in *source* that have been exported
using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
of the files specified by *source-pattern*.
The *source-pattern* is useful when the kernel-doc comments have been placed
in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
the function definitions.
Examples::
.. kernel-doc:: lib/bitmap.c
:export:
.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.c
internal: *[source-pattern ...]*
Include documentation for all functions and types in *source* that have
**not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
in *source* or in any of the files specified by *source-pattern*.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:internal:
doc: *title*
Include documentation for the ``DOC:`` paragraph identified by *title* in
*source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
is only used as an identifier for the paragraph, and is not included in the
output. Please make sure to have an appropriate heading in the enclosing
reStructuredText document.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port
functions: *function* *[...]*
Include documentation for each *function* in *source*.
Example::
.. kernel-doc:: lib/bitmap.c
:functions: bitmap_parselist bitmap_parselist_user
Without options, the kernel-doc directive includes all documentation comments
from the source file.
The kernel-doc extension is included in the kernel source tree, at
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
``scripts/kernel-doc`` script to extract the documentation comments from the
source.
.. _kernel_doc:
Writing kernel-doc comments
===========================
In order to provide embedded, "C" friendly, easy to maintain, but consistent and
extractable overview, function and type documentation, the Linux kernel has
adopted a consistent style for documentation comments. The format for this
documentation is called the kernel-doc format, described below. This style
embeds the documentation within the source files, using a few simple conventions
for adding documentation paragraphs and documenting functions and their
parameters, structures and unions and their members, enumerations, and typedefs.
.. note:: The kernel-doc format is deceptively similar to 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 ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
the documentation build to extract this embedded documentation into the various
HTML, PDF, and other format documents.
In order to provide good documentation of kernel functions and data structures,
please use the following conventions to format your kernel-doc comments in the
Linux kernel source.
How to format kernel-doc comments
---------------------------------
The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
comments so marked will be considered by the ``kernel-doc`` tool. Use it only
for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
should be used as the closing comment marker. The lines in between should be
prefixed by `` * `` (space star space).
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 function and type kernel-doc comments should be placed just before the
function or type being described. The overview kernel-doc comments may be freely
placed at the top indentation level.
.. note:: 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.
Example kernel-doc function comment::
/**
* foobar() - Brief description of foobar.
* @argument1: Description of parameter argument1 of foobar.
* @argument2: Description of parameter argument2 of foobar.
*
* Longer description of foobar.
*
* Context: Interrupt / locking context of foobar.
* Return: Description of return value of foobar.
*/
int foobar(int argument1, char *argument2)
The format is similar for documentation for structures, enums, paragraphs,
etc. See the sections below for specific details of each type.
The kernel-doc structure is extracted from the comments, and proper `Sphinx C
Domain`_ function and type descriptions with anchors are generated for them. The
descriptions are filtered for special kernel-doc highlights and
cross-references. See below for details.
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.
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
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.
Parameters and member arguments
-------------------------------
The kernel-doc function comments describe each parameter to the function and
function typedefs or each member of struct/union, in order, with the
``@argument:`` descriptions. For each non-private member argument, one
``@argument`` definition is needed.
The ``@argument:`` descriptions begin on the very next line following
the opening brief function description line, with no intervening blank
comment lines.
The ``@argument:`` descriptions may span multiple lines.
.. note::
If the ``@argument`` description has multiple lines, the continuation
of the description should be starting exactly at the same column as
the previous line, e. g.::
* @argument: some long description
* that continues on next lines
or::
* @argument:
* some long description
* that continues on next lines
If a function or typedef parameter argument is ``...`` (e. g. a variable
number of arguments), its description should be listed in kernel-doc
notation as::
* @...: description
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.
Private members
~~~~~~~~~~~~~~~
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.
How to format kernel-doc comments
---------------------------------
Example::
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.
/**
* 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;
};
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.
Function documentation
----------------------
......@@ -230,6 +76,34 @@ 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.
Function parameters
~~~~~~~~~~~~~~~~~~~
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.
.. note::
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
~~~~~~~~~~~~~~~~
......@@ -287,57 +161,119 @@ The general format of a struct, union, and enum kernel-doc comment is::
/**
* struct struct_name - Brief description.
* @argument: Description of member member_name.
* @member1: Description of member1.
* @member2: Description of member2.
* One can provide multiple line descriptions
* for members.
*
* Description of the structure.
*/
On the above, ``struct`` is used to mean structs. You can also use ``union``
and ``enum`` to describe unions and enums. ``argument`` is used
to mean struct and union member names as well as enumerations in an enum.
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.
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
~~~~~~~
The kernel-doc data structure comments describe each member of the structure,
in order, with the member descriptions.
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;
};
In-line member documentation comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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;
/** @foobar: Single line description. */
int foobar;
}
Nested structs/unions
~~~~~~~~~~~~~~~~~~~~~
It is possible to document nested structs unions, like::
It is possible to document nested structs and unions, like::
/**
* struct nested_foobar - a struct with nested unions and structs
* @arg1: - first argument of anonymous union/anonymous struct
* @arg2: - second argument of anonymous union/anonymous struct
* @arg3: - third argument of anonymous union/anonymous struct
* @arg4: - fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1 - first argument of struct st1 on union bar
* @bar.st1.arg2 - second argument of struct st1 on union bar
* @bar.st2.arg1 - first argument of struct st2 on union bar
* @bar.st2.arg2 - second argument of struct st2 on union bar
* @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.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 arg1;
int arg2;
int memb1;
int memb2;
}
struct {
void *arg3;
int arg4;
void *memb3;
int memb4;
}
}
union {
struct {
int arg1;
int arg2;
int memb1;
int memb2;
} st1;
struct {
void *arg1;
int arg2;
void *memb1;
int memb2;
} st2;
} bar;
};
......@@ -345,9 +281,9 @@ It is possible to document nested structs unions, like::
.. note::
#) When documenting nested structs or unions, if the struct/union ``foo``
is named, the argument ``bar`` inside it should be documented as
is named, the member ``bar`` inside it should be documented as
``@foo.bar:``
#) When the nested struct/union is anonymous, the argument ``bar`` on it
#) When the nested struct/union is anonymous, the member ``bar`` in it
should be documented as ``@bar:``
Typedef documentation
......@@ -375,7 +311,6 @@ Typedefs with function prototypes can also be documented::
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
Highlights and cross-references
-------------------------------
......@@ -447,37 +382,6 @@ cross-references.
For further details, please refer to the `Sphinx C Domain`_ documentation.
In-line member documentation comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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;
/** @foobar: Single line description. */
int foobar;
}
Overview documentation comments
-------------------------------
......@@ -507,22 +411,76 @@ 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.
Recommendations
---------------
Including kernel-doc comments
=============================
The documentation comments may be included in any of the reStructuredText
documents using a dedicated kernel-doc Sphinx directive extension.
The kernel-doc directive is of the format::
.. kernel-doc:: source
:option:
The *source* is the path to a source file, relative to the kernel source
tree. The following directive options are supported:
export: *[source-pattern ...]*
Include documentation for all functions in *source* that have been exported
using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
of the files specified by *source-pattern*.
The *source-pattern* is useful when the kernel-doc comments have been placed
in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
the function definitions.
Examples::
.. kernel-doc:: lib/bitmap.c
:export:
.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.c
internal: *[source-pattern ...]*
Include documentation for all functions and types in *source* that have
**not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
in *source* or in any of the files specified by *source-pattern*.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:internal:
doc: *title*
Include documentation for the ``DOC:`` paragraph identified by *title* in
*source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
is only used as an identifier for the paragraph, and is not included in the
output. Please make sure to have an appropriate heading in the enclosing
reStructuredText document.
We definitely need kernel-doc formatted documentation for functions that are
exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port
functions: *function* *[...]*
Include documentation for each *function* in *source*.
We also look to provide kernel-doc formatted documentation for functions
externally visible to other kernel files (not marked "static").
Example::
We also recommend providing kernel-doc formatted documentation for private (file
"static") routines, for consistency of kernel source code layout. But this is
lower priority and at the discretion of the MAINTAINER of that kernel source
file.
.. kernel-doc:: lib/bitmap.c
:functions: bitmap_parselist bitmap_parselist_user
Data structures visible in kernel include files should also be documented using
kernel-doc formatted comments.
Without options, the kernel-doc directive includes all documentation comments
from the source file.
The kernel-doc extension is included in the kernel source tree, at
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
``scripts/kernel-doc`` script to extract the documentation comments from the
source.
.. _kernel_doc:
How to use kernel-doc to generate man pages
-------------------------------------------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7