--- /dev/null
-The structure members may also be documented in-line within the definition::
+ 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/kernel-doc.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 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.
+ * @arg: Description of argument of foobar.
+ *
+ * Longer description of foobar.
+ *
+ * Return: Description of return value of foobar.
+ */
+ int foobar(int arg)
+
+ The format is similar for documentation for structures, enums, paragraphs,
+ etc. See the sections 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 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
+
+ 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.
+
+ .. attention:: 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.)
+
+ ``$ENVVAR``
+ Name of an environment variable. (No cross-referencing, just formatting.)
+
+ ``&struct name``
+ Structure reference.
+
+ ``&enum name``
+ Enum reference.
+
+ ``&typedef name``
+ Typedef reference.
+
+ ``&struct_name->member`` or ``&struct_name.member``
+ Structure or union member reference. The cross-reference will be to the struct
+ or union definition, not the member directly.
+
+ ``&name``
+ A generic type reference. Prefer using the full reference described above
+ instead. This is mostly for legacy comments.
+
+ Cross-referencing from reStructuredText
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ To cross-reference the functions and types defined in the kernel-doc comments
+ from reStructuredText documents, please use the `Sphinx C Domain`_
+ references. For example::
+
+ See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
+
+ While the type reference works with just the type name, without the
+ struct/union/enum/typedef part in front, you may want to use::
+
+ See :c:type:`struct foo <foo>`.
+ See :c:type:`union bar <bar>`.
+ See :c:type:`enum baz <baz>`.
+ See :c:type:`typedef meh <meh>`.
+
+ This will produce prettier links, and is in line with how kernel-doc does the
+ cross-references.
+
+ For further details, please refer to the `Sphinx C Domain`_ documentation.
+
+ Function documentation
+ ----------------------
+
+ 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.
+ *
+ * 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.
+
+ The kernel-doc function comments describe each parameter to the function, in
+ order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
+ must 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. The continuation lines may contain
+ indentation. If a function parameter is ``...`` (varargs), it should be listed
+ in kernel-doc notation as: ``@...:``.
+
+ The return value, if any, should be described in a dedicated section at the end
+ of the comment starting with "Return:".
+
+ Structure, union, and enumeration documentation
+ -----------------------------------------------
+
+ The general format of a struct, union, and enum kernel-doc comment is::
+
+ /**
+ * struct struct_name - Brief description.
+ * @member_name: Description of member member_name.
+ *
+ * Description of the structure.
+ */
+
+ Below, "struct" is used to mean structs, unions and enums, and "member" is used
+ to mean struct and union members 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 kernel-doc data structure comments describe each member of the structure, in
+ order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
+ begin on the very next line following the opening brief function description
+ line, with no intervening blank comment lines. The ``@member:`` descriptions may
+ span multiple lines. The continuation lines may contain indentation.
+
+ 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;
+ }
+
+ Private members
+ ~~~~~~~~~~~~~~~
+
+ Inside a struct 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
+ *
+ * Longer description
+ */
+ struct my_struct {
+ int a;
+ int b;
+ /* private: internal use only */
+ int c;
+ };
+
+
+ Typedef documentation
+ ---------------------
+
+ The general format of a typedef kernel-doc comment is::
+
+ /**
+ * typedef type_name - Brief description.
+ *
+ * Description of the type.
+ */
+
+ Overview documentation comments
+ -------------------------------
+
+ To facilitate having source code and comments close together, you can include
+ kernel-doc documentation blocks that are free-form comments instead of being
+ kernel-doc for functions, structures, unions, enums, or typedefs. This could be
+ used for something like a theory of operation for a driver or library code, for
+ example.
+
+ This is done by using a ``DOC:`` section keyword with a section title.
+
+ The general format of an overview or high-level documentation comment is::
+
+ /**
+ * DOC: Theory of Operation
+ *
+ * The whizbang foobar is a dilly of a gizmo. It can do whatever you
+ * want it to do, at any time. It reads your mind. Here's how it works.
+ *
+ * foo bar splat
+ *
+ * The only drawback to this gizmo is that is can sometimes damage
+ * hardware, software, or its subject(s).
+ */
+
+ 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
+ ---------------
+
+ We definitely need kernel-doc formatted documentation for functions that are
+ exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
+
+ We also look to 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. But this is
+ 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
+ kernel-doc formatted comments.
projects / linux-block.git / commitdiff