Documentation/doc-guide/kernel-doc.rst

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