378 lines · 13.0 KB · Text
RawDownload
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.) ````literal````  A literal block that should be handled as-is. The output will use a  ``monospaced font``.   Useful if you need to use special characters that would otherwise have some  meaning either by kernel-doc script of by reStructuredText.   This is particularly useful if you need to use things like ``%ph`` inside  a function description. ``$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.There are two styles, single-line comments where both the opening ``/**`` andclosing ``*/`` are on the same line, and multi-line comments where they are eachon 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:" commenttags. Structure fields that are inside a "private:" area are not listed in thegenerated output documentation.  The "private:" and "public:" tags must beginimmediately following a ``/*`` comment marker.  They may optionally includecomments 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 includekernel-doc documentation blocks that are free-form comments instead of beingkernel-doc for functions, structures, unions, enums, or typedefs. This could beused for something like a theory of operation for a driver or library code, forexample. 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 alsoas an identifier for extracting the documentation comment. Thus, the title mustbe unique within the file. Recommendations--------------- We definitely need kernel-doc formatted documentation for functions that areexported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. We also look to provide kernel-doc formatted documentation for functionsexternally 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 islower priority and at the discretion of the MAINTAINER of that kernel sourcefile. Data structures visible in kernel include files should also be documented usingkernel-doc formatted comments.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t