.. title:: Kernel-doc comments ===========================Writing kernel-doc comments=========================== The Linux kernel source files may contain structured documentationcomments in the kernel-doc format to describe the functions, typesand design of the code. It is easier to keep documentation up-to-datewhen it is embedded in source files. .. 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. .. note:: kernel-doc does not cover Rust code: please see   Documentation/rust/general-information.rst instead. The kernel-doc structure is extracted from the comments, and proper`Sphinx C Domain`_ function and type descriptions with anchors aregenerated from them. The descriptions are filtered for special kernel-dochighlights 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-doccomment. Functions and data structures in header files which are intendedto be used by modules should also have kernel-doc comments. It is good practice to also provide kernel-doc formatted documentationfor functions externally visible to other kernel files (not marked``static``). We also recommend providing kernel-doc formatteddocumentation for private (file ``static``) routines, for consistency ofkernel source code layout. This is lower priority and at the discretionof the maintainer of that kernel source file. How to format kernel-doc comments--------------------------------- The opening comment mark ``/**`` is used for kernel-doc comments. The``kernel-doc`` tool will extract comments marked this way. The rest ofthe comment is formatted like a normal multi-line comment with a columnof asterisks on the left side, closing with ``*/`` on a line by itself. The function and type kernel-doc comments should be placed just beforethe function or type being described in order to maximise the chancethat somebody changing the code will also change the documentation. Theoverview kernel-doc comments may be placed anywhere at the top indentationlevel. Running the ``kernel-doc`` tool with increased verbosity and without actualoutput generation may be used to verify proper formatting of thedocumentation comments. For example:: 	tools/docs/kernel-doc -v -none drivers/foo/bar.c The documentation format of ``.c`` files is also verified by the kernel buildwhen it is requested to perform extra gcc checks:: 	make W=n However, the above command does not verify header files. These should be checkedseparately using ``kernel-doc``. 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.   *   * Context: Describes whether the function can sleep, what locks it takes,   *          releases, or expects to be held. It can extend over multiple   *          lines.   * Return: Describe the return value of function_name.   *   * 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. Function parameters~~~~~~~~~~~~~~~~~~~ Each function argument should be described in order, immediately followingthe short function description.  Do not leave a blank line between thefunction 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 shouldbe written in kernel-doc notation as::       * @...: description Function context~~~~~~~~~~~~~~~~ The context in which a function can be called should be described in asection named ``Context``. This should include whether the functionsleeps or can be called from interrupt context, as well as what locksit takes, releases and expects to be held by its caller. Examples::   * Context: Any context.  * Context: Any context. Takes and releases the RCU lock.  * Context: Any context. Expects <lock> to be held by caller.  * Context: Process context. May sleep if @gfp flags permit.  * Context: Process context. Takes and releases <mutex>.  * Context: Softirq or process context. Takes and releases <lock>, BH-safe.  * Context: Interrupt context. Return values~~~~~~~~~~~~~ The return value, if any, should be described in a dedicated sectionnamed ``Return`` (or ``Returns``). .. note::   #) The multi-line descriptive text you provide does *not* recognize     line breaks, so if you try to format some text nicely, as in:: 	* Return:	* %0 - OK	* %-EINVAL - invalid argument	* %-ENOMEM - out of memory      this will all run together and produce:: 	Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory      So, in order to produce the desired line breaks, you need to use a     ReST list, e. g.::       * Return:      * * %0		- OK to runtime suspend the device      * * %-EBUSY	- Device should not be runtime suspended   #) If the descriptive text you provide has lines that begin with     some phrase followed by a colon, each of those phrases will be taken     as a new section heading, which probably won't produce the desired     effect. Structure, union, and enumeration documentation----------------------------------------------- The general format of a ``struct``, ``union``, and ``enum`` kernel-doccomment is::   /**   * struct struct_name - Brief description.   * @member1: Description of member1.   * @member2: Description of member2.   *           One can provide multiple line descriptions   *           for members.   *   * Description of the structure.   */ 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 multiplelines, and ends with a member description, a blank comment line, or theend of the comment block. Members~~~~~~~ Members of structs, unions and enums should be documented the same wayas function parameters; they immediately succeed the short descriptionand 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. When ``private:`` is used on nested structs, it propagates only to innerstructs/unions.  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;  }; Nested structs/unions~~~~~~~~~~~~~~~~~~~~~ It is possible to document nested structs and unions, like::       /**       * struct nested_foobar - a struct with nested unions and structs       * @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: non-anonymous union       * @bar.st1: struct st1 inside @bar       * @bar.st2: struct st2 inside @bar       * @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 memb1;            /* private: hides memb2 from documentation */            int memb2;          };          /* Everything here is public again, as private scope finished */          struct {            void *memb3;            int memb4;          };        };        union {          struct {            int memb1;            int memb2;          } st1;          struct {            void *memb1;            int memb2;          } st2;        } bar;      }; .. note::    #) When documenting nested structs or unions, if the ``struct``/``union``      ``foo`` is named, the member ``bar`` inside it should be documented as      ``@foo.bar:``   #) When the nested ``struct``/``union`` is anonymous, the member ``bar`` in      it should be documented as ``@bar:`` 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;        union {                /** @foobar: Single line description. */                int foobar;        };        /** @bar2: Description for struct @bar2 inside @foo */        struct {                /**                 * @bar2.barbar: Description for @barbar inside @foo.bar2                 */                int barbar;        } bar2;  }; Typedef documentation--------------------- The general format of a ``typedef`` kernel-doc comment is::   /**   * typedef type_name - Brief description.   *   * Description of the type.   */ Typedefs with function prototypes can also be documented::   /**   * typedef type_name - Brief description.   * @arg1: description of arg1   * @arg2: description of arg2   *   * Description of the type.   *   * Context: Locking context.   * Returns: Meaning of the return value.   */   typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); Variables documentation----------------------- The general format of a kernel-doc variable comment is::   /**   * var var_name - Brief description.   *   * Description of the var_name variable.   */   extern int var_name; Object-like macro documentation------------------------------- Object-like macros are distinct from function-like macros. They aredifferentiated by whether the macro name is immediately followed by aleft parenthesis ('(') for function-like macros or not followed by onefor object-like macros. Function-like macros are handled like functions by ``tools/docs/kernel-doc``.They may have a parameter list. Object-like macros have do not have aparameter list. The general format of an object-like macro kernel-doc comment is::   /**   * define object_name - Brief description.   *   * Description of the object.   */ Example::   /**   * define MAX_ERRNO - maximum errno value that is supported   *   * Kernel pointers have redundant information, so we can use a   * scheme where we can return either an error code or a normal   * pointer with the same return value.   */  #define MAX_ERRNO	4095 Example::   /**   * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \   *	Initializes struct drm_plane_helper_funcs for VRAM handling   *   * This macro initializes struct drm_plane_helper_funcs to use the   * respective helper functions.   */  #define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \	.prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \	.cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb  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.)   Examples::     %0    %NULL    %-1    %-EFAULT    %-EINVAL    %-ENOMEM ````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 or 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``  ``struct`` 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~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ No additional syntax is needed to cross-reference the functions and typesdefined in the kernel-doc comments from reStructuredText documents.Just end function names with ``()`` and write ``struct``, ``union``, ``enum``or ``typedef`` before types.For example::   See foo().  See struct foo.  See union bar.  See enum baz.  See typedef meh. However, if you want custom text in the cross-reference link, that can be donethrough the following syntax::   See :c:func:`my custom link text for function foo <foo>`.  See :c:type:`my custom link text for struct bar <bar>`. For further details, please refer to the `Sphinx C Domain`_ documentation. .. note::   Variables aren't automatically cross referenced. For those, you need to   explicitly add a C domain cross-reference. 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, typedefs or variables.This could be used for something like a theory of operation for a driver orlibrary code, for example. This is done by using a ``DOC:`` section keyword with a section title.

Lines 1–500 of 632. Load more