Documentation/doc-guide/kernel-doc.rst

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