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`` (or ``Returns``).
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 * Returns: 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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.