summaryrefslogtreecommitdiffstats
path: root/Documentation/doc-guide/kernel-doc.rst
diff options
context:
space:
mode:
authorMatthew Wilcox <mawilcox@microsoft.com>2018-02-13 22:15:37 +0100
committerJonathan Corbet <corbet@lwn.net>2018-02-13 22:22:01 +0100
commit46347502b099d9cff0b635a2eb33c27de9b80b80 (patch)
treeb1810bf9772ce5d26412eaeb0fc73b918b13608e /Documentation/doc-guide/kernel-doc.rst
parentFix whitespace in example (diff)
downloadlinux-46347502b099d9cff0b635a2eb33c27de9b80b80.tar.xz
linux-46347502b099d9cff0b635a2eb33c27de9b80b80.zip
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>
Diffstat (limited to 'Documentation/doc-guide/kernel-doc.rst')
-rw-r--r--Documentation/doc-guide/kernel-doc.rst476
1 files changed, 217 insertions, 259 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 85efec8ecc44..2fb7f2bfc245 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -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.
-
-.. 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 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 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).
+.. 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 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.
+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
-
-Private members
-~~~~~~~~~~~~~~~
+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.
-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.
+How to format kernel-doc comments
+---------------------------------
-The ``private:`` and ``public:`` tags must begin immediately following a
-``/*`` comment marker. They may optionally include comments between the
-``:`` and the ending ``*/`` marker.
+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.
-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.
+
+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:
-We definitely need kernel-doc formatted documentation for functions that are
-exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
+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*.
-We also look to provide kernel-doc formatted documentation for functions
-externally visible to other kernel files (not marked "static").
+ 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.
-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.
+ Examples::
-Data structures visible in kernel include files should also be documented using
-kernel-doc formatted comments.
+ .. 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
-------------------------------------------