Documentation/doc-guide/kernel-doc.rst

   1 Writing kernel-doc comments
   2 ===========================
   3
   4 The Linux kernel source files may contain structured documentation
   5 comments in the kernel-doc format to describe the functions, types
   6 and design of the code. It is easier to keep documentation up-to-date
   7 when it is embedded in source files.
   8
   9 .. note:: The kernel-doc format is deceptively similar to javadoc,
  10    gtk-doc or Doxygen, yet distinctively different, for historical
  11    reasons. The kernel source contains tens of thousands of kernel-doc
  12    comments. Please stick to the style described here.
  13
  14 The kernel-doc structure is extracted from the comments, and proper
  15 `Sphinx C Domain`_ function and type descriptions with anchors are
  16 generated from them. The descriptions are filtered for special kernel-doc
  17 highlights and cross-references. See below for details.
  18
  19 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
  20
  21 Every function that is exported to loadable modules using
  22 ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
  23 comment. Functions and data structures in header files which are intended
  24 to be used by modules should also have kernel-doc comments.
  25
  26 It is good practice to also provide kernel-doc formatted documentation
  27 for functions externally visible to other kernel files (not marked
  28 ``static``). We also recommend providing kernel-doc formatted
  29 documentation for private (file ``static``) routines, for consistency of
  30 kernel source code layout. This is lower priority and at the discretion
  31 of the maintainer of that kernel source file.
  32
  33 How to format kernel-doc comments
  34 ---------------------------------
  35
  36 The opening comment mark ``/**`` is used for kernel-doc comments. The
  37 ``kernel-doc`` tool will extract comments marked this way. The rest of
  38 the comment is formatted like a normal multi-line comment with a column
  39 of asterisks on the left side, closing with ``*/`` on a line by itself.
  40
  41 The function and type kernel-doc comments should be placed just before
  42 the function or type being described in order to maximise the chance
  43 that somebody changing the code will also change the documentation. The
  44 overview kernel-doc comments may be placed anywhere at the top indentation
  45 level.
  46
  47 Running the ``kernel-doc`` tool with increased verbosity and without actual
  48 output generation may be used to verify proper formatting of the
  49 documentation comments. For example::
  50
  51         scripts/kernel-doc -v -none drivers/foo/bar.c
  52
  53 The documentation format is verified by the kernel build when it is
  54 requested to perform extra gcc checks::
  55
  56         make W=n
  57
  58 Function documentation
  59 ----------------------
  60
  61 The general format of a function and function-like macro kernel-doc comment is::
  62
  63   /**
  64    * function_name() - Brief description of function.
  65    * @arg1: Describe the first argument.
  66    * @arg2: Describe the second argument.
  67    *        One can provide multiple line descriptions
  68    *        for arguments.
  69    *
  70    * A longer description, with more discussion of the function function_name()
  71    * that might be useful to those using or modifying it. Begins with an
  72    * empty comment line, and may include additional embedded empty
  73    * comment lines.
  74    *
  75    * The longer description may have multiple paragraphs.
  76    *
  77    * Context: Describes whether the function can sleep, what locks it takes,
  78    *          releases, or expects to be held. It can extend over multiple
  79    *          lines.
  80    * Return: Describe the return value of function_name.
  81    *
  82    * The return value description can also have multiple paragraphs, and should
  83    * be placed at the end of the comment block.
  84    */
  85
  86 The brief description following the function name may span multiple lines, and
  87 ends with an argument description, a blank comment line, or the end of the
  88 comment block.
  89
  90 Function parameters
  91 ~~~~~~~~~~~~~~~~~~~
  92
  93 Each function argument should be described in order, immediately following
  94 the short function description.  Do not leave a blank line between the
  95 function description and the arguments, nor between the arguments.
  96
  97 Each ``@argument:`` description may span multiple lines.
  98
  99 .. note::
 100
 101    If the ``@argument`` description has multiple lines, the continuation
 102    of the description should start at the same column as the previous line::
 103
 104       * @argument: some long description
 105       *            that continues on next lines
 106
 107    or::
 108
 109       * @argument:
 110       *         some long description
 111       *         that continues on next lines
 112
 113 If a function has a variable number of arguments, its description should
 114 be written in kernel-doc notation as::
 115
 116       * @...: description
 117
 118 Function context
 119 ~~~~~~~~~~~~~~~~
 120
 121 The context in which a function can be called should be described in a
 122 section named ``Context``. This should include whether the function
 123 sleeps or can be called from interrupt context, as well as what locks
 124 it takes, releases and expects to be held by its caller.
 125
 126 Examples::
 127
 128   * Context: Any context.
 129   * Context: Any context. Takes and releases the RCU lock.
 130   * Context: Any context. Expects <lock> to be held by caller.
 131   * Context: Process context. May sleep if @gfp flags permit.
 132   * Context: Process context. Takes and releases <mutex>.
 133   * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
 134   * Context: Interrupt context.
 135
 136 Return values
 137 ~~~~~~~~~~~~~
 138
 139 The return value, if any, should be described in a dedicated section
 140 named ``Return``.
 141
 142 .. note::
 143
 144   #) The multi-line descriptive text you provide does *not* recognize
 145      line breaks, so if you try to format some text nicely, as in::
 146
 147         * Return:
 148         * 0 - OK
 149         * -EINVAL - invalid argument
 150         * -ENOMEM - out of memory
 151
 152      this will all run together and produce::
 153
 154         Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
 155
 156      So, in order to produce the desired line breaks, you need to use a
 157      ReST list, e. g.::
 158
 159       * Return:
 160       * * 0             - OK to runtime suspend the device
 161       * * -EBUSY        - Device should not be runtime suspended
 162
 163   #) If the descriptive text you provide has lines that begin with
 164      some phrase followed by a colon, each of those phrases will be taken
 165      as a new section heading, which probably won't produce the desired
 166      effect.
 167
 168 Structure, union, and enumeration documentation
 169 -----------------------------------------------
 170
 171 The general format of a struct, union, and enum kernel-doc comment is::
 172
 173   /**
 174    * struct struct_name - Brief description.
 175    * @member1: Description of member1.
 176    * @member2: Description of member2.
 177    *           One can provide multiple line descriptions
 178    *           for members.
 179    *
 180    * Description of the structure.
 181    */
 182
 183 You can replace the ``struct`` in the above example with ``union`` or
 184 ``enum``  to describe unions or enums. ``member`` is used to mean struct
 185 and union member names as well as enumerations in an enum.
 186
 187 The brief description following the structure name may span multiple
 188 lines, and ends with a member description, a blank comment line, or the
 189 end of the comment block.
 190
 191 Members
 192 ~~~~~~~
 193
 194 Members of structs, unions and enums should be documented the same way
 195 as function parameters; they immediately succeed the short description
 196 and may be multi-line.
 197
 198 Inside a struct or union description, you can use the ``private:`` and
 199 ``public:`` comment tags. Structure fields that are inside a ``private:``
 200 area are not listed in the generated output documentation.
 201
 202 The ``private:`` and ``public:`` tags must begin immediately following a
 203 ``/*`` comment marker. They may optionally include comments between the
 204 ``:`` and the ending ``*/`` marker.
 205
 206 Example::
 207
 208   /**
 209    * struct my_struct - short description
 210    * @a: first member
 211    * @b: second member
 212    * @d: fourth member
 213    *
 214    * Longer description
 215    */
 216   struct my_struct {
 217       int a;
 218       int b;
 219   /* private: internal use only */
 220       int c;
 221   /* public: the next one is public */
 222       int d;
 223   };
 224
 225 Nested structs/unions
 226 ~~~~~~~~~~~~~~~~~~~~~
 227
 228 It is possible to document nested structs and unions, like::
 229
 230       /**
 231        * struct nested_foobar - a struct with nested unions and structs
 232        * @memb1: first member of anonymous union/anonymous struct
 233        * @memb2: second member of anonymous union/anonymous struct
 234        * @memb3: third member of anonymous union/anonymous struct
 235        * @memb4: fourth member of anonymous union/anonymous struct
 236        * @bar: non-anonymous union
 237        * @bar.st1: struct st1 inside @bar
 238        * @bar.st2: struct st2 inside @bar
 239        * @bar.st1.memb1: first member of struct st1 on union bar
 240        * @bar.st1.memb2: second member of struct st1 on union bar
 241        * @bar.st2.memb1: first member of struct st2 on union bar
 242        * @bar.st2.memb2: second member of struct st2 on union bar
 243        */
 244       struct nested_foobar {
 245         /* Anonymous union/struct*/
 246         union {
 247           struct {
 248             int memb1;
 249             int memb2;
 250           };
 251           struct {
 252             void *memb3;
 253             int memb4;
 254           };
 255         };
 256         union {
 257           struct {
 258             int memb1;
 259             int memb2;
 260           } st1;
 261           struct {
 262             void *memb1;
 263             int memb2;
 264           } st2;
 265         } bar;
 266       };
 267
 268 .. note::
 269
 270    #) When documenting nested structs or unions, if the struct/union ``foo``
 271       is named, the member ``bar`` inside it should be documented as
 272       ``@foo.bar:``
 273    #) When the nested struct/union is anonymous, the member ``bar`` in it
 274       should be documented as ``@bar:``
 275
 276 In-line member documentation comments
 277 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 278
 279 The structure members may also be documented in-line within the definition.
 280 There are two styles, single-line comments where both the opening ``/**`` and
 281 closing ``*/`` are on the same line, and multi-line comments where they are each
 282 on a line of their own, like all other kernel-doc comments::
 283
 284   /**
 285    * struct foo - Brief description.
 286    * @foo: The Foo member.
 287    */
 288   struct foo {
 289         int foo;
 290         /**
 291          * @bar: The Bar member.
 292          */
 293         int bar;
 294         /**
 295          * @baz: The Baz member.
 296          *
 297          * Here, the member description may contain several paragraphs.
 298          */
 299         int baz;
 300         union {
 301                 /** @foobar: Single line description. */
 302                 int foobar;
 303         };
 304         /** @bar2: Description for struct @bar2 inside @foo */
 305         struct {
 306                 /**
 307                  * @bar2.barbar: Description for @barbar inside @foo.bar2
 308                  */
 309                 int barbar;
 310         } bar2;
 311   };
 312
 313 Typedef documentation
 314 ---------------------
 315
 316 The general format of a typedef kernel-doc comment is::
 317
 318   /**
 319    * typedef type_name - Brief description.
 320    *
 321    * Description of the type.
 322    */
 323
 324 Typedefs with function prototypes can also be documented::
 325
 326   /**
 327    * typedef type_name - Brief description.
 328    * @arg1: description of arg1
 329    * @arg2: description of arg2
 330    *
 331    * Description of the type.
 332    *
 333    * Context: Locking context.
 334    * Return: Meaning of the return value.
 335    */
 336    typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
 337
 338 Highlights and cross-references
 339 -------------------------------
 340
 341 The following special patterns are recognized in the kernel-doc comment
 342 descriptive text and converted to proper reStructuredText markup and `Sphinx C
 343 Domain`_ references.
 344
 345 .. attention:: The below are **only** recognized within kernel-doc comments,
 346                **not** within normal reStructuredText documents.
 347
 348 ``funcname()``
 349   Function reference.
 350
 351 ``@parameter``
 352   Name of a function parameter. (No cross-referencing, just formatting.)
 353
 354 ``%CONST``
 355   Name of a constant. (No cross-referencing, just formatting.)
 356
 357 ````literal````
 358   A literal block that should be handled as-is. The output will use a
 359   ``monospaced font``.
 360
 361   Useful if you need to use special characters that would otherwise have some
 362   meaning either by kernel-doc script or by reStructuredText.
 363
 364   This is particularly useful if you need to use things like ``%ph`` inside
 365   a function description.
 366
 367 ``$ENVVAR``
 368   Name of an environment variable. (No cross-referencing, just formatting.)
 369
 370 ``&struct name``
 371   Structure reference.
 372
 373 ``&enum name``
 374   Enum reference.
 375
 376 ``&typedef name``
 377   Typedef reference.
 378
 379 ``&struct_name->member`` or ``&struct_name.member``
 380   Structure or union member reference. The cross-reference will be to the struct
 381   or union definition, not the member directly.
 382
 383 ``&name``
 384   A generic type reference. Prefer using the full reference described above
 385   instead. This is mostly for legacy comments.
 386
 387 Cross-referencing from reStructuredText
 388 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 389
 390 No additional syntax is needed to cross-reference the functions and types
 391 defined in the kernel-doc comments from reStructuredText documents.
 392 Just end function names with ``()`` and write ``struct``, ``union``, ``enum``
 393 or ``typedef`` before types.
 394 For example::
 395
 396   See foo().
 397   See struct foo.
 398   See union bar.
 399   See enum baz.
 400   See typedef meh.
 401
 402 However, if you want custom text in the cross-reference link, that can be done
 403 through the following syntax::
 404
 405   See :c:func:`my custom link text for function foo <foo>`.
 406   See :c:type:`my custom link text for struct bar <bar>`.
 407
 408 For further details, please refer to the `Sphinx C Domain`_ documentation.
 409
 410 Overview documentation comments
 411 -------------------------------
 412
 413 To facilitate having source code and comments close together, you can include
 414 kernel-doc documentation blocks that are free-form comments instead of being
 415 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
 416 used for something like a theory of operation for a driver or library code, for
 417 example.
 418
 419 This is done by using a ``DOC:`` section keyword with a section title.
 420
 421 The general format of an overview or high-level documentation comment is::
 422
 423   /**
 424    * DOC: Theory of Operation
 425    *
 426    * The whizbang foobar is a dilly of a gizmo. It can do whatever you
 427    * want it to do, at any time. It reads your mind. Here's how it works.
 428    *
 429    * foo bar splat
 430    *
 431    * The only drawback to this gizmo is that is can sometimes damage
 432    * hardware, software, or its subject(s).
 433    */
 434
 435 The title following ``DOC:`` acts as a heading within the source file, but also
 436 as an identifier for extracting the documentation comment. Thus, the title must
 437 be unique within the file.
 438
 439 Including kernel-doc comments
 440 =============================
 441
 442 The documentation comments may be included in any of the reStructuredText
 443 documents using a dedicated kernel-doc Sphinx directive extension.
 444
 445 The kernel-doc directive is of the format::
 446
 447   .. kernel-doc:: source
 448      :option:
 449
 450 The *source* is the path to a source file, relative to the kernel source
 451 tree. The following directive options are supported:
 452
 453 export: *[source-pattern ...]*
 454   Include documentation for all functions in *source* that have been exported
 455   using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
 456   of the files specified by *source-pattern*.
 457
 458   The *source-pattern* is useful when the kernel-doc comments have been placed
 459   in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
 460   the function definitions.
 461
 462   Examples::
 463
 464     .. kernel-doc:: lib/bitmap.c
 465        :export:
 466
 467     .. kernel-doc:: include/net/mac80211.h
 468        :export: net/mac80211/*.c
 469
 470 internal: *[source-pattern ...]*
 471   Include documentation for all functions and types in *source* that have
 472   **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
 473   in *source* or in any of the files specified by *source-pattern*.
 474
 475   Example::
 476
 477     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
 478        :internal:
 479
 480 identifiers: *[ function/type ...]*
 481   Include documentation for each *function* and *type* in *source*.
 482   If no *function* is specified, the documentation for all functions
 483   and types in the *source* will be included.
 484
 485   Examples::
 486
 487     .. kernel-doc:: lib/bitmap.c
 488        :identifiers: bitmap_parselist bitmap_parselist_user
 489
 490     .. kernel-doc:: lib/idr.c
 491        :identifiers:
 492
 493 no-identifiers: *[ function/type ...]*
 494   Exclude documentation for each *function* and *type* in *source*.
 495
 496   Example::
 497
 498     .. kernel-doc:: lib/bitmap.c
 499        :no-identifiers: bitmap_parselist
 500
 501 functions: *[ function/type ...]*
 502   This is an alias of the 'identifiers' directive and deprecated.
 503
 504 doc: *title*
 505   Include documentation for the ``DOC:`` paragraph identified by *title* in
 506   *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
 507   is only used as an identifier for the paragraph, and is not included in the
 508   output. Please make sure to have an appropriate heading in the enclosing
 509   reStructuredText document.
 510
 511   Example::
 512
 513     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
 514        :doc: High Definition Audio over HDMI and Display Port
 515
 516 Without options, the kernel-doc directive includes all documentation comments
 517 from the source file.
 518
 519 The kernel-doc extension is included in the kernel source tree, at
 520 ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
 521 ``scripts/kernel-doc`` script to extract the documentation comments from the
 522 source.
 523
 524 .. _kernel_doc:
 525
 526 How to use kernel-doc to generate man pages
 527 -------------------------------------------
 528
 529 If you just want to use kernel-doc to generate man pages you can do this
 530 from the kernel git tree::
 531
 532   $ scripts/kernel-doc -man \
 533     $(git grep -l '/\*\*' -- :^Documentation :^tools) \
 534     | scripts/split-man.pl /tmp/man
 535
 536 Some older versions of git do not support some of the variants of syntax for
 537 path exclusion.  One of the following commands may work for those versions::
 538
 539   $ scripts/kernel-doc -man \
 540     $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
 541     | scripts/split-man.pl /tmp/man
 542
 543   $ scripts/kernel-doc -man \
 544     $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
 545     | scripts/split-man.pl /tmp/man