Documentation/doc-guide/kernel-doc.rst

   1 Including kernel-doc comments
   2 =============================
   3
   4 The Linux kernel source files may contain structured documentation comments, or
   5 kernel-doc comments to describe the functions and types and design of the
   6 code. The documentation comments may be included to any of the reStructuredText
   7 documents using a dedicated kernel-doc Sphinx directive extension.
   8
   9 The kernel-doc directive is of the format::
  10
  11   .. kernel-doc:: source
  12      :option:
  13
  14 The *source* is the path to a source file, relative to the kernel source
  15 tree. The following directive options are supported:
  16
  17 export: *[source-pattern ...]*
  18   Include documentation for all functions in *source* that have been exported
  19   using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
  20   of the files specified by *source-pattern*.
  21
  22   The *source-pattern* is useful when the kernel-doc comments have been placed
  23   in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
  24   the function definitions.
  25
  26   Examples::
  27
  28     .. kernel-doc:: lib/bitmap.c
  29        :export:
  30
  31     .. kernel-doc:: include/net/mac80211.h
  32        :export: net/mac80211/*.c
  33
  34 internal: *[source-pattern ...]*
  35   Include documentation for all functions and types in *source* that have
  36   **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
  37   in *source* or in any of the files specified by *source-pattern*.
  38
  39   Example::
  40
  41     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
  42        :internal:
  43
  44 doc: *title*
  45   Include documentation for the ``DOC:`` paragraph identified by *title* in
  46   *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
  47   is only used as an identifier for the paragraph, and is not included in the
  48   output. Please make sure to have an appropriate heading in the enclosing
  49   reStructuredText document.
  50
  51   Example::
  52
  53     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
  54        :doc: High Definition Audio over HDMI and Display Port
  55
  56 functions: *function* *[...]*
  57   Include documentation for each *function* in *source*.
  58
  59   Example::
  60
  61     .. kernel-doc:: lib/bitmap.c
  62        :functions: bitmap_parselist bitmap_parselist_user
  63
  64 Without options, the kernel-doc directive includes all documentation comments
  65 from the source file.
  66
  67 The kernel-doc extension is included in the kernel source tree, at
  68 ``Documentation/sphinx/kernel-doc.py``. Internally, it uses the
  69 ``scripts/kernel-doc`` script to extract the documentation comments from the
  70 source.
  71
  72 .. _kernel_doc:
  73
  74 Writing kernel-doc comments
  75 ===========================
  76
  77 In order to provide embedded, "C" friendly, easy to maintain, but consistent and
  78 extractable overview, function and type documentation, the Linux kernel has
  79 adopted a consistent style for documentation comments. The format for this
  80 documentation is called the kernel-doc format, described below. This style
  81 embeds the documentation within the source files, using a few simple conventions
  82 for adding documentation paragraphs and documenting functions and their
  83 parameters, structures and unions and their members, enumerations, and typedefs.
  84
  85 .. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen,
  86    yet distinctively different, for historical reasons. The kernel source
  87    contains tens of thousands of kernel-doc comments. Please stick to the style
  88    described here.
  89
  90 The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
  91 the documentation build to extract this embedded documentation into the various
  92 HTML, PDF, and other format documents.
  93
  94 In order to provide good documentation of kernel functions and data structures,
  95 please use the following conventions to format your kernel-doc comments in the
  96 Linux kernel source.
  97
  98 How to format kernel-doc comments
  99 ---------------------------------
 100
 101 The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
 102 comments so marked will be considered by the ``kernel-doc`` tool. Use it only
 103 for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
 104 should be used as the closing comment marker. The lines in between should be
 105 prefixed by `` * `` (space star space).
 106
 107 The function and type kernel-doc comments should be placed just before the
 108 function or type being described. The overview kernel-doc comments may be freely
 109 placed at the top indentation level.
 110
 111 Example kernel-doc function comment::
 112
 113   /**
 114    * foobar() - Brief description of foobar.
 115    * @arg: Description of argument of foobar.
 116    *
 117    * Longer description of foobar.
 118    *
 119    * Return: Description of return value of foobar.
 120    */
 121   int foobar(int arg)
 122
 123 The format is similar for documentation for structures, enums, paragraphs,
 124 etc. See the sections below for details.
 125
 126 The kernel-doc structure is extracted from the comments, and proper `Sphinx C
 127 Domain`_ function and type descriptions with anchors are generated for them. The
 128 descriptions are filtered for special kernel-doc highlights and
 129 cross-references. See below for details.
 130
 131 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
 132
 133 Highlights and cross-references
 134 -------------------------------
 135
 136 The following special patterns are recognized in the kernel-doc comment
 137 descriptive text and converted to proper reStructuredText markup and `Sphinx C
 138 Domain`_ references.
 139
 140 .. attention:: The below are **only** recognized within kernel-doc comments,
 141                **not** within normal reStructuredText documents.
 142
 143 ``funcname()``
 144   Function reference.
 145
 146 ``@parameter``
 147   Name of a function parameter. (No cross-referencing, just formatting.)
 148
 149 ``%CONST``
 150   Name of a constant. (No cross-referencing, just formatting.)
 151
 152 ````literal````
 153   A literal block that should be handled as-is. The output will use a
 154   ``monospaced font``.
 155
 156   Useful if you need to use special characters that would otherwise have some
 157   meaning either by kernel-doc script of by reStructuredText.
 158
 159   This is particularly useful if you need to use things like ``%ph`` inside
 160   a function description.
 161
 162 ``$ENVVAR``
 163   Name of an environment variable. (No cross-referencing, just formatting.)
 164
 165 ``&struct name``
 166   Structure reference.
 167
 168 ``&enum name``
 169   Enum reference.
 170
 171 ``&typedef name``
 172   Typedef reference.
 173
 174 ``&struct_name->member`` or ``&struct_name.member``
 175   Structure or union member reference. The cross-reference will be to the struct
 176   or union definition, not the member directly.
 177
 178 ``&name``
 179   A generic type reference. Prefer using the full reference described above
 180   instead. This is mostly for legacy comments.
 181
 182 Cross-referencing from reStructuredText
 183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 184
 185 To cross-reference the functions and types defined in the kernel-doc comments
 186 from reStructuredText documents, please use the `Sphinx C Domain`_
 187 references. For example::
 188
 189   See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
 190
 191 While the type reference works with just the type name, without the
 192 struct/union/enum/typedef part in front, you may want to use::
 193
 194   See :c:type:`struct foo <foo>`.
 195   See :c:type:`union bar <bar>`.
 196   See :c:type:`enum baz <baz>`.
 197   See :c:type:`typedef meh <meh>`.
 198
 199 This will produce prettier links, and is in line with how kernel-doc does the
 200 cross-references.
 201
 202 For further details, please refer to the `Sphinx C Domain`_ documentation.
 203
 204 Function documentation
 205 ----------------------
 206
 207 The general format of a function and function-like macro kernel-doc comment is::
 208
 209   /**
 210    * function_name() - Brief description of function.
 211    * @arg1: Describe the first argument.
 212    * @arg2: Describe the second argument.
 213    *        One can provide multiple line descriptions
 214    *        for arguments.
 215    *
 216    * A longer description, with more discussion of the function function_name()
 217    * that might be useful to those using or modifying it. Begins with an
 218    * empty comment line, and may include additional embedded empty
 219    * comment lines.
 220    *
 221    * The longer description may have multiple paragraphs.
 222    *
 223    * Return: Describe the return value of foobar.
 224    *
 225    * The return value description can also have multiple paragraphs, and should
 226    * be placed at the end of the comment block.
 227    */
 228
 229 The brief description following the function name may span multiple lines, and
 230 ends with an ``@argument:`` description, a blank comment line, or the end of the
 231 comment block.
 232
 233 The kernel-doc function comments describe each parameter to the function, in
 234 order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
 235 must begin on the very next line following the opening brief function
 236 description line, with no intervening blank comment lines. The ``@argument:``
 237 descriptions may span multiple lines. The continuation lines may contain
 238 indentation. If a function parameter is ``...`` (varargs), it should be listed
 239 in kernel-doc notation as: ``@...:``.
 240
 241 The return value, if any, should be described in a dedicated section at the end
 242 of the comment starting with "Return:".
 243
 244 Structure, union, and enumeration documentation
 245 -----------------------------------------------
 246
 247 The general format of a struct, union, and enum kernel-doc comment is::
 248
 249   /**
 250    * struct struct_name - Brief description.
 251    * @member_name: Description of member member_name.
 252    *
 253    * Description of the structure.
 254    */
 255
 256 Below, "struct" is used to mean structs, unions and enums, and "member" is used
 257 to mean struct and union members as well as enumerations in an enum.
 258
 259 The brief description following the structure name may span multiple lines, and
 260 ends with a ``@member:`` description, a blank comment line, or the end of the
 261 comment block.
 262
 263 The kernel-doc data structure comments describe each member of the structure, in
 264 order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
 265 begin on the very next line following the opening brief function description
 266 line, with no intervening blank comment lines. The ``@member:`` descriptions may
 267 span multiple lines. The continuation lines may contain indentation.
 268
 269 In-line member documentation comments
 270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 271
 272 The structure members may also be documented in-line within the definition.
 273 There are two styles, single-line comments where both the opening ``/**`` and
 274 closing ``*/`` are on the same line, and multi-line comments where they are each
 275 on a line of their own, like all other kernel-doc comments::
 276
 277   /**
 278    * struct foo - Brief description.
 279    * @foo: The Foo member.
 280    */
 281   struct foo {
 282         int foo;
 283         /**
 284          * @bar: The Bar member.
 285          */
 286         int bar;
 287         /**
 288          * @baz: The Baz member.
 289          *
 290          * Here, the member description may contain several paragraphs.
 291          */
 292         int baz;
 293         /** @foobar: Single line description. */
 294         int foobar;
 295   }
 296
 297 Private members
 298 ~~~~~~~~~~~~~~~
 299
 300 Inside a struct description, you can use the "private:" and "public:" comment
 301 tags. Structure fields that are inside a "private:" area are not listed in the
 302 generated output documentation.  The "private:" and "public:" tags must begin
 303 immediately following a ``/*`` comment marker.  They may optionally include
 304 comments between the ``:`` and the ending ``*/`` marker.
 305
 306 Example::
 307
 308   /**
 309    * struct my_struct - short description
 310    * @a: first member
 311    * @b: second member
 312    *
 313    * Longer description
 314    */
 315   struct my_struct {
 316       int a;
 317       int b;
 318   /* private: internal use only */
 319       int c;
 320   };
 321
 322
 323 Typedef documentation
 324 ---------------------
 325
 326 The general format of a typedef kernel-doc comment is::
 327
 328   /**
 329    * typedef type_name - Brief description.
 330    *
 331    * Description of the type.
 332    */
 333
 334 Overview documentation comments
 335 -------------------------------
 336
 337 To facilitate having source code and comments close together, you can include
 338 kernel-doc documentation blocks that are free-form comments instead of being
 339 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
 340 used for something like a theory of operation for a driver or library code, for
 341 example.
 342
 343 This is done by using a ``DOC:`` section keyword with a section title.
 344
 345 The general format of an overview or high-level documentation comment is::
 346
 347   /**
 348    * DOC: Theory of Operation
 349    *
 350    * The whizbang foobar is a dilly of a gizmo. It can do whatever you
 351    * want it to do, at any time. It reads your mind. Here's how it works.
 352    *
 353    * foo bar splat
 354    *
 355    * The only drawback to this gizmo is that is can sometimes damage
 356    * hardware, software, or its subject(s).
 357    */
 358
 359 The title following ``DOC:`` acts as a heading within the source file, but also
 360 as an identifier for extracting the documentation comment. Thus, the title must
 361 be unique within the file.
 362
 363 Recommendations
 364 ---------------
 365
 366 We definitely need kernel-doc formatted documentation for functions that are
 367 exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
 368
 369 We also look to provide kernel-doc formatted documentation for functions
 370 externally visible to other kernel files (not marked "static").
 371
 372 We also recommend providing kernel-doc formatted documentation for private (file
 373 "static") routines, for consistency of kernel source code layout. But this is
 374 lower priority and at the discretion of the MAINTAINER of that kernel source
 375 file.
 376
 377 Data structures visible in kernel include files should also be documented using
 378 kernel-doc formatted comments.