1.. title:: Kernel-doc comments 2 3=========================== 4Writing kernel-doc comments 5=========================== 6 7The Linux kernel source files may contain structured documentation 8comments in the kernel-doc format to describe the functions, types 9and design of the code. It is easier to keep documentation up-to-date 10when 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 20The kernel-doc structure is extracted from the comments, and proper 21`Sphinx C Domain`_ function and type descriptions with anchors are 22generated from them. The descriptions are filtered for special kernel-doc 23highlights and cross-references. See below for details. 24 25.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html 26 27Every function that is exported to loadable modules using 28``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc 29comment. Functions and data structures in header files which are intended 30to be used by modules should also have kernel-doc comments. 31 32It is good practice to also provide kernel-doc formatted documentation 33for functions externally visible to other kernel files (not marked 34``static``). We also recommend providing kernel-doc formatted 35documentation for private (file ``static``) routines, for consistency of 36kernel source code layout. This is lower priority and at the discretion 37of the maintainer of that kernel source file. 38 39How to format kernel-doc comments 40--------------------------------- 41 42The opening comment mark ``/**`` is used for kernel-doc comments. The 43``kernel-doc`` tool will extract comments marked this way. The rest of 44the comment is formatted like a normal multi-line comment with a column 45of asterisks on the left side, closing with ``*/`` on a line by itself. 46 47The function and type kernel-doc comments should be placed just before 48the function or type being described in order to maximise the chance 49that somebody changing the code will also change the documentation. The 50overview kernel-doc comments may be placed anywhere at the top indentation 51level. 52 53Running the ``kernel-doc`` tool with increased verbosity and without actual 54output generation may be used to verify proper formatting of the 55documentation comments. For example:: 56 57 scripts/kernel-doc -v -none drivers/foo/bar.c 58 59The documentation format is verified by the kernel build when it is 60requested to perform extra gcc checks:: 61 62 make W=n 63 64Function documentation 65---------------------- 66 67The 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 92The brief description following the function name may span multiple lines, and 93ends with an argument description, a blank comment line, or the end of the 94comment block. 95 96Function parameters 97~~~~~~~~~~~~~~~~~~~ 98 99Each function argument should be described in order, immediately following 100the short function description. Do not leave a blank line between the 101function description and the arguments, nor between the arguments. 102 103Each ``@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 119If a function has a variable number of arguments, its description should 120be written in kernel-doc notation as:: 121 122 * @...: description 123 124Function context 125~~~~~~~~~~~~~~~~ 126 127The context in which a function can be called should be described in a 128section named ``Context``. This should include whether the function 129sleeps or can be called from interrupt context, as well as what locks 130it takes, releases and expects to be held by its caller. 131 132Examples:: 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 142Return values 143~~~~~~~~~~~~~ 144 145The return value, if any, should be described in a dedicated section 146named ``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 174Structure, union, and enumeration documentation 175----------------------------------------------- 176 177The 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 189You can replace the ``struct`` in the above example with ``union`` or 190``enum`` to describe unions or enums. ``member`` is used to mean struct 191and union member names as well as enumerations in an enum. 192 193The brief description following the structure name may span multiple 194lines, and ends with a member description, a blank comment line, or the 195end of the comment block. 196 197Members 198~~~~~~~ 199 200Members of structs, unions and enums should be documented the same way 201as function parameters; they immediately succeed the short description 202and may be multi-line. 203 204Inside a struct or union description, you can use the ``private:`` and 205``public:`` comment tags. Structure fields that are inside a ``private:`` 206area are not listed in the generated output documentation. 207 208The ``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 212Example:: 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 231Nested structs/unions 232~~~~~~~~~~~~~~~~~~~~~ 233 234It 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 282In-line member documentation comments 283~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 284 285The structure members may also be documented in-line within the definition. 286There are two styles, single-line comments where both the opening ``/**`` and 287closing ``*/`` are on the same line, and multi-line comments where they are each 288on 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 319Typedef documentation 320--------------------- 321 322The 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 330Typedefs 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 344Highlights and cross-references 345------------------------------- 346 347The following special patterns are recognized in the kernel-doc comment 348descriptive text and converted to proper reStructuredText markup and `Sphinx C 349Domain`_ references. 350 351.. attention:: The below are **only** recognized within kernel-doc comments, 352 **not** within normal reStructuredText documents. 353 354``funcname()`` 355 Function reference. 356 357``@parameter`` 358 Name of a function parameter. (No cross-referencing, just formatting.) 359 360``%CONST`` 361 Name of a constant. (No cross-referencing, just formatting.) 362 363````literal```` 364 A literal block that should be handled as-is. The output will use a 365 ``monospaced font``. 366 367 Useful if you need to use special characters that would otherwise have some 368 meaning either by kernel-doc script or by reStructuredText. 369 370 This is particularly useful if you need to use things like ``%ph`` inside 371 a function description. 372 373``$ENVVAR`` 374 Name of an environment variable. (No cross-referencing, just formatting.) 375 376``&struct name`` 377 Structure reference. 378 379``&enum name`` 380 Enum reference. 381 382``&typedef name`` 383 Typedef reference. 384 385``&struct_name->member`` or ``&struct_name.member`` 386 Structure or union member reference. The cross-reference will be to the struct 387 or union definition, not the member directly. 388 389``&name`` 390 A generic type reference. Prefer using the full reference described above 391 instead. This is mostly for legacy comments. 392 393Cross-referencing from reStructuredText 394~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 395 396No additional syntax is needed to cross-reference the functions and types 397defined in the kernel-doc comments from reStructuredText documents. 398Just end function names with ``()`` and write ``struct``, ``union``, ``enum`` 399or ``typedef`` before types. 400For example:: 401 402 See foo(). 403 See struct foo. 404 See union bar. 405 See enum baz. 406 See typedef meh. 407 408However, if you want custom text in the cross-reference link, that can be done 409through the following syntax:: 410 411 See :c:func:`my custom link text for function foo <foo>`. 412 See :c:type:`my custom link text for struct bar <bar>`. 413 414For further details, please refer to the `Sphinx C Domain`_ documentation. 415 416Overview documentation comments 417------------------------------- 418 419To facilitate having source code and comments close together, you can include 420kernel-doc documentation blocks that are free-form comments instead of being 421kernel-doc for functions, structures, unions, enums, or typedefs. This could be 422used for something like a theory of operation for a driver or library code, for 423example. 424 425This is done by using a ``DOC:`` section keyword with a section title. 426 427The general format of an overview or high-level documentation comment is:: 428 429 /** 430 * DOC: Theory of Operation 431 * 432 * The whizbang foobar is a dilly of a gizmo. It can do whatever you 433 * want it to do, at any time. It reads your mind. Here's how it works. 434 * 435 * foo bar splat 436 * 437 * The only drawback to this gizmo is that is can sometimes damage 438 * hardware, software, or its subject(s). 439 */ 440 441The title following ``DOC:`` acts as a heading within the source file, but also 442as an identifier for extracting the documentation comment. Thus, the title must 443be unique within the file. 444 445============================= 446Including kernel-doc comments 447============================= 448 449The documentation comments may be included in any of the reStructuredText 450documents using a dedicated kernel-doc Sphinx directive extension. 451 452The kernel-doc directive is of the format:: 453 454 .. kernel-doc:: source 455 :option: 456 457The *source* is the path to a source file, relative to the kernel source 458tree. The following directive options are supported: 459 460export: *[source-pattern ...]* 461 Include documentation for all functions in *source* that have been exported 462 using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any 463 of the files specified by *source-pattern*. 464 465 The *source-pattern* is useful when the kernel-doc comments have been placed 466 in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to 467 the function definitions. 468 469 Examples:: 470 471 .. kernel-doc:: lib/bitmap.c 472 :export: 473 474 .. kernel-doc:: include/net/mac80211.h 475 :export: net/mac80211/*.c 476 477internal: *[source-pattern ...]* 478 Include documentation for all functions and types in *source* that have 479 **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either 480 in *source* or in any of the files specified by *source-pattern*. 481 482 Example:: 483 484 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 485 :internal: 486 487identifiers: *[ function/type ...]* 488 Include documentation for each *function* and *type* in *source*. 489 If no *function* is specified, the documentation for all functions 490 and types in the *source* will be included. 491 492 Examples:: 493 494 .. kernel-doc:: lib/bitmap.c 495 :identifiers: bitmap_parselist bitmap_parselist_user 496 497 .. kernel-doc:: lib/idr.c 498 :identifiers: 499 500no-identifiers: *[ function/type ...]* 501 Exclude documentation for each *function* and *type* in *source*. 502 503 Example:: 504 505 .. kernel-doc:: lib/bitmap.c 506 :no-identifiers: bitmap_parselist 507 508functions: *[ function/type ...]* 509 This is an alias of the 'identifiers' directive and deprecated. 510 511doc: *title* 512 Include documentation for the ``DOC:`` paragraph identified by *title* in 513 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* 514 is only used as an identifier for the paragraph, and is not included in the 515 output. Please make sure to have an appropriate heading in the enclosing 516 reStructuredText document. 517 518 Example:: 519 520 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 521 :doc: High Definition Audio over HDMI and Display Port 522 523Without options, the kernel-doc directive includes all documentation comments 524from the source file. 525 526The kernel-doc extension is included in the kernel source tree, at 527``Documentation/sphinx/kerneldoc.py``. Internally, it uses the 528``scripts/kernel-doc`` script to extract the documentation comments from the 529source. 530 531.. _kernel_doc: 532 533How to use kernel-doc to generate man pages 534------------------------------------------- 535 536If you just want to use kernel-doc to generate man pages you can do this 537from the kernel git tree:: 538 539 $ scripts/kernel-doc -man \ 540 $(git grep -l '/\*\*' -- :^Documentation :^tools) \ 541 | scripts/split-man.pl /tmp/man 542 543Some older versions of git do not support some of the variants of syntax for 544path exclusion. One of the following commands may work for those versions:: 545 546 $ scripts/kernel-doc -man \ 547 $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ 548 | scripts/split-man.pl /tmp/man 549 550 $ scripts/kernel-doc -man \ 551 $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ 552 | scripts/split-man.pl /tmp/man 553