Debian Codegraph @

Documentation/doc-guide/kernel-doc.rst

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