==========================Linux Kernel Documentation========================== Introduction============ The Linux kernel uses `Sphinx`_ to generate pretty documentation from`reStructuredText`_ files under ``Documentation``. To build the documentation inHTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generateddocumentation is placed in ``Documentation/output``. .. _Sphinx: http://www.sphinx-doc.org/.. _reStructuredText: http://docutils.sourceforge.net/rst.html The reStructuredText files may contain directives to include structureddocumentation comments, or kernel-doc comments, from source files. Usually theseare used to describe the functions and types and design of the code. Thekernel-doc comments have some special structure and formatting, but beyond thatthey are also treated as reStructuredText. There is also the deprecated DocBook toolchain to generate documentation fromDocBook XML template files under ``Documentation/DocBook``. The DocBook filesare to be converted to reStructuredText, and the toolchain is slated to beremoved. Finally, there are thousands of plain text documentation files scattered around``Documentation``. Some of these will likely be converted to reStructuredTextover time, but the bulk of them will remain in plain text. Sphinx Build============ The usual way to generate the documentation is to run ``make htmldocs`` or``make pdfdocs``. There are also other formats available, see the documentationsection of ``make help``. The generated documentation is placed informat-specific subdirectories under ``Documentation/output``. To generate documentation, Sphinx (``sphinx-build``) must obviously beinstalled. For prettier HTML output, the Read the Docs Sphinx theme(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is alsoneeded. All of these are widely available and packaged in distributions. To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` makevariable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verboseoutput. To remove the generated documentation, run ``make cleandocs``. Writing Documentation===================== Adding new documentation can be as simple as: 1. Add a new ``.rst`` file somewhere under ``Documentation``.2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``. .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html This is usually good enough for simple documentation (like the one you'rereading right now), but for larger documents it may be advisable to create asubdirectory (or use an existing one). For example, the graphics subsystemdocumentation is under ``Documentation/gpu``, split to several ``.rst`` files,and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced fromthe main index. See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can dowith them. In particular, the Sphinx `reStructuredText Primer`_ is a good placeto get started with reStructuredText. There are also some `Sphinx specificmarkup constructs`_. .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html Specific guidelines for the kernel documentation------------------------------------------------ Here are some specific guidelines for the kernel documentation: * Please don't go overboard with reStructuredText markup. Keep it simple. * Please stick to this order of heading adornments: 1. ``=`` with overline for document title:: ============== Document title ============== 2. ``=`` for chapters:: Chapters ======== 3. ``-`` for sections:: Section ------- 4. ``~`` for subsections:: Subsection ~~~~~~~~~~ Although RST doesn't mandate a specific order ("Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered."), having the higher levels the same overall makes it easier to follow the documents. the C domain------------ The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. afunction prototype: .. code-block:: rst .. c:function:: int ioctl( int fd, int request ) The C domain of the kernel-doc has some additional features. E.g. you can*rename* the reference name of a function with a common name like ``open`` or``ioctl``: .. code-block:: rst .. c:function:: int ioctl( int fd, int request ) :name: VIDIOC_LOG_STATUS The func-name (e.g. ioctl) remains in the output but the ref-name changed from``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is alsochanged to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: .. code-block:: rst :c:func:`VIDIOC_LOG_STATUS` list tables----------- We recommend the use of *list table* formats. The *list table* formats aredouble-stage lists. Compared to the ASCII-art they might not be ascomfortable for readers of the text files. Their advantage is that they are easy tocreate or modify and that the diff of a modification is much more meaningful,because it is limited to the modified content. The ``flat-table`` is a double-stage list similar to the ``list-table`` withsome additional features: * column-span: with the role ``cspan`` a cell can be extended through additional columns * row-span: with the role ``rspan`` a cell can be extended through additional rows * auto span rightmost cell of a table row over the missing cells on the right side of that table-row. With Option ``:fill-cells:`` this behavior can changed from *auto span* to *auto fill*, which automatically inserts (empty) cells instead of spanning the last cell. options: * ``:header-rows:`` [int] count of header rows* ``:stub-columns:`` [int] count of stub columns* ``:widths:`` [[int] [int] ... ] widths of columns* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells roles: * ``:cspan:`` [int] additional columns (*morecols*)* ``:rspan:`` [int] additional rows (*morerows*) The example below shows how to use this markup. The first level of the stagedlist is the *table-row*. In the *table-row* there is only one markup allowed,the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row<last row>`). .. code-block:: rst .. flat-table:: table title :widths: 2 1 1 3 * - head col 1 - head col 2 - head col 3 - head col 4 * - column 1 - field 1.1 - field 1.2 with autospan * - column 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`last row`: - column 3 Rendered as: .. flat-table:: table title :widths: 2 1 1 3 * - head col 1 - head col 2 - head col 3 - head col 4 * - column 1 - field 1.1 - field 1.2 with autospan * - column 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`last row`: - column 3 Including kernel-doc comments============================= The Linux kernel source files may contain structured documentation comments, orkernel-doc comments to describe the functions and types and design of thecode. The documentation comments may be included to any of the reStructuredTextdocuments 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 sourcetree. 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 commentsfrom 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 thesource. .. _kernel_doc: Writing kernel-doc comments=========================== In order to provide embedded, "C" friendly, easy to maintain, but consistent andextractable overview, function and type documentation, the Linux kernel hasadopted a consistent style for documentation comments. The format for thisdocumentation is called the kernel-doc format, described below. This styleembeds the documentation within the source files, using a few simple conventionsfor adding documentation paragraphs and documenting functions and theirparameters, 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 inthe documentation build to extract this embedded documentation into the variousHTML, 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 theLinux kernel source. How to format kernel-doc comments--------------------------------- The opening comment mark ``/**`` is reserved for kernel-doc comments. Onlycomments so marked will be considered by the ``kernel-doc`` tool. Use it onlyfor comment blocks that contain kernel-doc formatted comments. The usual ``*/``should be used as the closing comment marker. The lines in between should beprefixed by `` * `` (space star space). The function and type kernel-doc comments should be placed just before thefunction or type being described. The overview kernel-doc comments may be freelyplaced 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 CDomain`_ function and type descriptions with anchors are generated for them. Thedescriptions are filtered for special kernel-doc highlights andcross-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 commentdescriptive text and converted to proper reStructuredText markup and `Sphinx CDomain`_ 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 commentsfrom 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 thestruct/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 thecross-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, andends with an ``@argument:`` description, a blank comment line, or the end of thecomment block. The kernel-doc function comments describe each parameter to the function, inorder, with the ``@argument:`` descriptions. The ``@argument:`` descriptionsmust begin on the very next line following the opening brief functiondescription line, with no intervening blank comment lines. The ``@argument:``descriptions may span multiple lines. The continuation lines may containindentation. If a function parameter is ``...`` (varargs), it should be listedin kernel-doc notation as: ``@...:``. The return value, if any, should be described in a dedicated section at the endof 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 usedto mean struct and union members as well as enumerations in an enum. The brief description following the structure name may span multiple lines, andends with a ``@member:`` description, a blank comment line, or the end of thecomment block. The kernel-doc data structure comments describe each member of the structure, inorder, with the ``@member:`` descriptions. The ``@member:`` descriptions mustbegin on the very next line following the opening brief function descriptionline, with no intervening blank comment lines. The ``@member:`` descriptions mayspan 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:: /** * struct foo - Brief description. * @foo: The Foo member. */ struct foo { int foo; /** * @bar: The Bar member. */ int bar; /** * @baz: The Baz member.Lines 1–500 of 679. Load more
========================== Linux Kernel Documentation ========================== Introduction ============ The Linux kernel uses `Sphinx`_ to generate pretty documentation from `reStructuredText`_ files under ``Documentation``. To build the documentation in HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated documentation is placed in ``Documentation/output``. .. _Sphinx: http://www.sphinx-doc.org/ .. _reStructuredText: http://docutils.sourceforge.net/rst.html The reStructuredText files may contain directives to include structured documentation comments, or kernel-doc comments, from source files. Usually these are used to describe the functions and types and design of the code. The kernel-doc comments have some special structure and formatting, but beyond that they are also treated as reStructuredText. There is also the deprecated DocBook toolchain to generate documentation from DocBook XML template files under ``Documentation/DocBook``. The DocBook files are to be converted to reStructuredText, and the toolchain is slated to be removed. Finally, there are thousands of plain text documentation files scattered around ``Documentation``. Some of these will likely be converted to reStructuredText over time, but the bulk of them will remain in plain text. Sphinx Build ============ The usual way to generate the documentation is to run ``make htmldocs`` or ``make pdfdocs``. There are also other formats available, see the documentation section of ``make help``. The generated documentation is placed in format-specific subdirectories under ``Documentation/output``. To generate documentation, Sphinx (``sphinx-build``) must obviously be installed. For prettier HTML output, the Read the Docs Sphinx theme (``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also needed. All of these are widely available and packaged in distributions. To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose output. To remove the generated documentation, run ``make cleandocs``. Writing Documentation ===================== Adding new documentation can be as simple as: 1. Add a new ``.rst`` file somewhere under ``Documentation``. 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``. .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html This is usually good enough for simple documentation (like the one you're reading right now), but for larger documents it may be advisable to create a subdirectory (or use an existing one). For example, the graphics subsystem documentation is under ``Documentation/gpu``, split to several ``.rst`` files, and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from the main index. See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place to get started with reStructuredText. There are also some `Sphinx specific markup constructs`_. .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html Specific guidelines for the kernel documentation ------------------------------------------------ Here are some specific guidelines for the kernel documentation: * Please don't go overboard with reStructuredText markup. Keep it simple. * Please stick to this order of heading adornments: 1. ``=`` with overline for document title:: ============== Document title ============== 2. ``=`` for chapters:: Chapters ======== 3. ``-`` for sections:: Section ------- 4. ``~`` for subsections:: Subsection ~~~~~~~~~~ Although RST doesn't mandate a specific order ("Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered."), having the higher levels the same overall makes it easier to follow the documents. the C domain ------------ The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a function prototype: .. code-block:: rst .. c:function:: int ioctl( int fd, int request ) The C domain of the kernel-doc has some additional features. E.g. you can *rename* the reference name of a function with a common name like ``open`` or ``ioctl``: .. code-block:: rst .. c:function:: int ioctl( int fd, int request ) :name: VIDIOC_LOG_STATUS The func-name (e.g. ioctl) remains in the output but the ref-name changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: .. code-block:: rst :c:func:`VIDIOC_LOG_STATUS` list tables ----------- We recommend the use of *list table* formats. The *list table* formats are double-stage lists. Compared to the ASCII-art they might not be as comfortable for readers of the text files. Their advantage is that they are easy to create or modify and that the diff of a modification is much more meaningful, because it is limited to the modified content. The ``flat-table`` is a double-stage list similar to the ``list-table`` with some additional features: * column-span: with the role ``cspan`` a cell can be extended through additional columns * row-span: with the role ``rspan`` a cell can be extended through additional rows * auto span rightmost cell of a table row over the missing cells on the right side of that table-row. With Option ``:fill-cells:`` this behavior can changed from *auto span* to *auto fill*, which automatically inserts (empty) cells instead of spanning the last cell. options: * ``:header-rows:`` [int] count of header rows * ``:stub-columns:`` [int] count of stub columns * ``:widths:`` [[int] [int] ... ] widths of columns * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells roles: * ``:cspan:`` [int] additional columns (*morecols*) * ``:rspan:`` [int] additional rows (*morerows*) The example below shows how to use this markup. The first level of the staged list is the *table-row*. In the *table-row* there is only one markup allowed, the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` ) and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row <last row>`). .. code-block:: rst .. flat-table:: table title :widths: 2 1 1 3 * - head col 1 - head col 2 - head col 3 - head col 4 * - column 1 - field 1.1 - field 1.2 with autospan * - column 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`last row`: - column 3 Rendered as: .. flat-table:: table title :widths: 2 1 1 3 * - head col 1 - head col 2 - head col 3 - head col 4 * - column 1 - field 1.1 - field 1.2 with autospan * - column 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`last row`: - column 3 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:: /** * struct foo - Brief description. * @foo: The Foo member. */ struct foo { int foo; /** * @bar: The Bar member. */ int bar; /** * @baz: The Baz member.