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: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Matthew Wilcox
Jonathan Corbet
parent
9831e5548a
commit
46347502b0
|
|
@ -1,202 +1,48 @@
|
|||
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.
|
||||
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.
|
||||
|
||||
.. 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.
|
||||
.. 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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
.. _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.
|
||||
|
||||
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.
|
||||
|
||||
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 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. The overview kernel-doc comments may be freely
|
||||
placed at the top indentation level.
|
||||
|
||||
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.
|
||||
|
||||
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
|
||||
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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;
|
||||
};
|
||||
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.
|
||||
|
||||
The kernel-doc data structure comments describe each member of the structure,
|
||||
in order, with the member descriptions.
|
||||
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;
|
||||
};
|
||||
|
||||
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
|
||||
=============================
|
||||
|
||||
We definitely need kernel-doc formatted documentation for functions that are
|
||||
exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
|
||||
The documentation comments may be included in any of the reStructuredText
|
||||
documents using a dedicated kernel-doc Sphinx directive extension.
|
||||
|
||||
We also look to provide kernel-doc formatted documentation for functions
|
||||
externally visible to other kernel files (not marked "static").
|
||||
The kernel-doc directive is of the format::
|
||||
|
||||
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:: source
|
||||
:option:
|
||||
|
||||
Data structures visible in kernel include files should also be documented using
|
||||
kernel-doc formatted comments.
|
||||
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:
|
||||
|
||||
How to use kernel-doc to generate man pages
|
||||
-------------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue