ich777/linux_media
1
0
Fork 0
mirror of https://github.com/tbsdtv/linux_media.git synced 2025-07-23 12:43:29 +02:00
Code Issues Packages Projects Releases Wiki Activity

Restructure kernel-doc.rst

Browse Source 
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
2018-02-13 13:15:37 -08:00
committed by Jonathan Corbet
parent 9831e5548a
commit 46347502b0
1 changed files with 218 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

478
Documentation/doc-guide/kernel-doc.rst
View File

@@ -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 Writing kernel-doc comments
=========================== ===========================
In order to provide embedded, "C" friendly, easy to maintain, but consistent and The Linux kernel source files may contain structured documentation
extractable overview, function and type documentation, the Linux kernel has comments in the kernel-doc format to describe the functions, types
adopted a consistent style for documentation comments. The format for this and design of the code. It is easier to keep documentation up-to-date
documentation is called the kernel-doc format, described below. This style when it is embedded in source files.
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, .. note:: The kernel-doc format is deceptively similar to javadoc,
yet distinctively different, for historical reasons. The kernel source gtk-doc or Doxygen, yet distinctively different, for historical
contains tens of thousands of kernel-doc comments. Please stick to the style reasons. The kernel source contains tens of thousands of kernel-doc
described here. comments. Please stick to the style described here.
The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in The kernel-doc structure is extracted from the comments, and proper
the documentation build to extract this embedded documentation into the various `Sphinx C Domain`_ function and type descriptions with anchors are
HTML, PDF, and other format documents. 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, .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
please use the following conventions to format your kernel-doc comments in the
Linux kernel source. 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 How to format kernel-doc comments
--------------------------------- ---------------------------------
The opening comment mark ``/**`` is reserved for kernel-doc comments. Only The opening comment mark ``/**`` is used for kernel-doc comments. The
comments so marked will be considered by the ``kernel-doc`` tool. Use it only ``kernel-doc`` tool will extract comments marked this way. The rest of
for comment blocks that contain kernel-doc formatted comments. The usual ``*/`` the comment is formatted like a normal multi-line comment with a column
should be used as the closing comment marker. The lines in between should be of asterisks on the left side, closing with ``*/`` on a line by itself.
prefixed by `` * `` (space star space).
The function and type kernel-doc comments should be placed just before the The function and type kernel-doc comments should be placed just before
function or type being described. The overview kernel-doc comments may be freely the function or type being described in order to maximise the chance
placed at the top indentation level. that somebody changing the code will also change the documentation. The
overview kernel-doc comments may be placed anywhere at the top indentation
Example kernel-doc function comment:: level.
/**
* 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;
};
Function documentation 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 ends with an argument description, a blank comment line, or the end of the
comment block. 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 Function context
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@@ -287,57 +161,119 @@ The general format of a struct, union, and enum kernel-doc comment is::
/** /**
* struct struct_name - Brief description. * 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. * Description of the structure.
*/ */
On the above, ``struct`` is used to mean structs. You can also use ``union`` You can replace the ``struct`` in the above example with ``union`` or
and ``enum`` to describe unions and enums. ``argument`` is used ``enum`` to describe unions or enums. ``member`` is used to mean struct
to mean struct and union member names as well as enumerations in an enum. and union member names as well as enumerations in an enum.
The brief description following the structure name may span multiple lines, and The brief description following the structure name may span multiple
ends with a member description, a blank comment line, or the end of the lines, and ends with a member description, a blank comment line, or the
comment block. end of the comment block.
The kernel-doc data structure comments describe each member of the structure, Members
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 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 * struct nested_foobar - a struct with nested unions and structs
* @arg1: - first argument of anonymous union/anonymous struct * @memb1: first member of anonymous union/anonymous struct
* @arg2: - second argument of anonymous union/anonymous struct * @memb2: second member of anonymous union/anonymous struct
* @arg3: - third argument of anonymous union/anonymous struct * @memb3: third member of anonymous union/anonymous struct
* @arg4: - fourth argument of anonymous union/anonymous struct * @memb4: fourth member of anonymous union/anonymous struct
* @bar.st1.arg1 - first argument of struct st1 on union bar * @bar.st1.memb1: first member of struct st1 on union bar
* @bar.st1.arg2 - second argument of struct st1 on union bar * @bar.st1.memb2: second member of struct st1 on union bar
* @bar.st2.arg1 - first argument of struct st2 on union bar * @bar.st2.memb1: first member of struct st2 on union bar
* @bar.st2.arg2 - second argument of struct st2 on union bar * @bar.st2.memb2: second member of struct st2 on union bar
struct nested_foobar { struct nested_foobar {
/* Anonymous union/struct*/ /* Anonymous union/struct*/
union { union {
struct { struct {
int arg1; int memb1;
int arg2; int memb2;
} }
struct { struct {
void *arg3; void *memb3;
int arg4; int memb4;
} }
} }
union { union {
struct { struct {
int arg1; int memb1;
int arg2; int memb2;
} st1; } st1;
struct { struct {
void *arg1; void *memb1;
int arg2; int memb2;
} st2; } st2;
} bar; } bar;
}; };
@@ -345,9 +281,9 @@ It is possible to document nested structs unions, like::
.. note:: .. note::
#) When documenting nested structs or unions, if the struct/union ``foo`` #) 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:`` ``@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:`` should be documented as ``@bar:``
Typedef documentation Typedef documentation
@@ -375,7 +311,6 @@ Typedefs with function prototypes can also be documented::
*/ */
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
Highlights and cross-references Highlights and cross-references
------------------------------- -------------------------------
@@ -447,37 +382,6 @@ cross-references.
For further details, please refer to the `Sphinx C Domain`_ documentation. 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 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 as an identifier for extracting the documentation comment. Thus, the title must
be unique within the file. be unique within the file.
Recommendations Including kernel-doc comments
--------------- =============================
We definitely need kernel-doc formatted documentation for functions that are The documentation comments may be included in any of the reStructuredText
exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. documents using a dedicated kernel-doc Sphinx directive extension.
We also look to provide kernel-doc formatted documentation for functions The kernel-doc directive is of the format::
externally visible to other kernel files (not marked "static").
We also recommend providing kernel-doc formatted documentation for private (file .. kernel-doc:: source
"static") routines, for consistency of kernel source code layout. But this is :option:
lower priority and at the discretion of the MAINTAINER of that kernel source
file.
Data structures visible in kernel include files should also be documented using The *source* is the path to a source file, relative to the kernel source
kernel-doc formatted comments. 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 How to use kernel-doc to generate man pages
------------------------------------------- -------------------------------------------