Commit | Line | Data |
---|---|---|
5372de4e AY |
1 | .. title:: Kernel-doc comments |
2 | ||
980c3799 | 3 | =========================== |
17defc28 JN |
4 | Writing kernel-doc comments |
5 | =========================== | |
6 | ||
46347502 MW |
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. | |
17defc28 | 11 | |
46347502 MW |
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. | |
17defc28 | 16 | |
d07479b2 MO |
17 | .. note:: kernel-doc does not cover Rust code: please see |
18 | Documentation/rust/general-information.rst instead. | |
19 | ||
46347502 MW |
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. | |
17defc28 JN |
24 | |
25 | .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html | |
26 | ||
46347502 MW |
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. | |
63ac8517 | 31 | |
46347502 MW |
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. | |
01f2c180 | 38 | |
46347502 MW |
39 | How to format kernel-doc comments |
40 | --------------------------------- | |
01f2c180 | 41 | |
46347502 MW |
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. | |
01f2c180 | 46 | |
46347502 MW |
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. | |
01f2c180 | 52 | |
8fcce580 MR |
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 | ||
fc275bf3 MCC |
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 | * | |
da70b8c4 MW |
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. | |
1bb37a35 | 86 | * Return: Describe the return value of function_name. |
fc275bf3 MCC |
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 | ||
46347502 MW |
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 | ||
da70b8c4 MW |
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 | ||
fc275bf3 MCC |
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 | |
dcb50d97 | 171 | as a new section heading, which probably won't produce the desired |
fc275bf3 MCC |
172 | effect. |
173 | ||
553aa3c1 MCC |
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. | |
46347502 MW |
181 | * @member1: Description of member1. |
182 | * @member2: Description of member2. | |
183 | * One can provide multiple line descriptions | |
184 | * for members. | |
553aa3c1 MCC |
185 | * |
186 | * Description of the structure. | |
187 | */ | |
188 | ||
46347502 MW |
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. | |
553aa3c1 | 192 | |
46347502 MW |
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 | ~~~~~~~ | |
553aa3c1 | 199 | |
46347502 MW |
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 | ||
8ad72163 MCC |
231 | Nested structs/unions |
232 | ~~~~~~~~~~~~~~~~~~~~~ | |
233 | ||
46347502 | 234 | It is possible to document nested structs and unions, like:: |
8ad72163 MCC |
235 | |
236 | /** | |
237 | * struct nested_foobar - a struct with nested unions and structs | |
46347502 MW |
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 | |
3651d452 MCC |
242 | * @bar: non-anonymous union |
243 | * @bar.st1: struct st1 inside @bar | |
244 | * @bar.st2: struct st2 inside @bar | |
46347502 MW |
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 | |
3651d452 | 249 | */ |
8ad72163 MCC |
250 | struct nested_foobar { |
251 | /* Anonymous union/struct*/ | |
252 | union { | |
253 | struct { | |
46347502 MW |
254 | int memb1; |
255 | int memb2; | |
91135840 | 256 | }; |
8ad72163 | 257 | struct { |
46347502 MW |
258 | void *memb3; |
259 | int memb4; | |
91135840 BW |
260 | }; |
261 | }; | |
dcb50d97 | 262 | union { |
8ad72163 | 263 | struct { |
46347502 MW |
264 | int memb1; |
265 | int memb2; | |
dcb50d97 | 266 | } st1; |
8ad72163 | 267 | struct { |
46347502 MW |
268 | void *memb1; |
269 | int memb2; | |
dcb50d97 MW |
270 | } st2; |
271 | } bar; | |
8ad72163 MCC |
272 | }; |
273 | ||
274 | .. note:: | |
275 | ||
276 | #) When documenting nested structs or unions, if the struct/union ``foo`` | |
46347502 | 277 | is named, the member ``bar`` inside it should be documented as |
8ad72163 | 278 | ``@foo.bar:`` |
46347502 | 279 | #) When the nested struct/union is anonymous, the member ``bar`` in it |
8ad72163 | 280 | should be documented as ``@bar:`` |
553aa3c1 | 281 | |
d2253a45 MCC |
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; | |
dbcce2bf MCC |
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; | |
d2253a45 MCC |
317 | }; |
318 | ||
bdb76f9e MCC |
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. | |
da70b8c4 MW |
338 | * |
339 | * Context: Locking context. | |
340 | * Return: Meaning of the return value. | |
bdb76f9e MCC |
341 | */ |
342 | typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); | |
343 | ||
17defc28 JN |
344 | Highlights and cross-references |
345 | ------------------------------- | |
346 | ||
347 | The following special patterns are recognized in the kernel-doc comment | |
348 | descriptive text and converted to proper reStructuredText markup and `Sphinx C | |
349 | Domain`_ 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 | ||
5d47c31b MCC |
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 | |
9159ba14 | 368 | meaning either by kernel-doc script or by reStructuredText. |
5d47c31b MCC |
369 | |
370 | This is particularly useful if you need to use things like ``%ph`` inside | |
371 | a function description. | |
372 | ||
17defc28 JN |
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 | ||
393 | Cross-referencing from reStructuredText | |
394 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
395 | ||
7c8b9e30 NP |
396 | No additional syntax is needed to cross-reference the functions and types |
397 | defined in the kernel-doc comments from reStructuredText documents. | |
398 | Just end function names with ``()`` and write ``struct``, ``union``, ``enum`` | |
399 | or ``typedef`` before types. | |
400 | For example:: | |
401 | ||
402 | See foo(). | |
403 | See struct foo. | |
404 | See union bar. | |
405 | See enum baz. | |
406 | See typedef meh. | |
407 | ||
408 | However, if you want custom text in the cross-reference link, that can be done | |
409 | through 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>`. | |
17defc28 JN |
413 | |
414 | For further details, please refer to the `Sphinx C Domain`_ documentation. | |
415 | ||
17defc28 JN |
416 | Overview documentation comments |
417 | ------------------------------- | |
418 | ||
419 | To facilitate having source code and comments close together, you can include | |
420 | kernel-doc documentation blocks that are free-form comments instead of being | |
421 | kernel-doc for functions, structures, unions, enums, or typedefs. This could be | |
422 | used for something like a theory of operation for a driver or library code, for | |
423 | example. | |
424 | ||
425 | This is done by using a ``DOC:`` section keyword with a section title. | |
426 | ||
427 | The 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 | ||
441 | The title following ``DOC:`` acts as a heading within the source file, but also | |
442 | as an identifier for extracting the documentation comment. Thus, the title must | |
443 | be unique within the file. | |
444 | ||
980c3799 | 445 | ============================= |
46347502 MW |
446 | Including kernel-doc comments |
447 | ============================= | |
448 | ||
449 | The documentation comments may be included in any of the reStructuredText | |
450 | documents using a dedicated kernel-doc Sphinx directive extension. | |
451 | ||
452 | The kernel-doc directive is of the format:: | |
453 | ||
454 | .. kernel-doc:: source | |
455 | :option: | |
456 | ||
457 | The *source* is the path to a source file, relative to the kernel source | |
458 | tree. The following directive options are supported: | |
17defc28 | 459 | |
46347502 MW |
460 | export: *[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*. | |
17defc28 | 464 | |
46347502 MW |
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. | |
17defc28 | 468 | |
46347502 | 469 | Examples:: |
17defc28 | 470 | |
46347502 MW |
471 | .. kernel-doc:: lib/bitmap.c |
472 | :export: | |
473 | ||
474 | .. kernel-doc:: include/net/mac80211.h | |
475 | :export: net/mac80211/*.c | |
476 | ||
477 | internal: *[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 | ||
36bc683d CD |
487 | identifiers: *[ 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 | ||
2791f47d MCC |
500 | no-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 | ||
36bc683d CD |
508 | functions: *[ function/type ...]* |
509 | This is an alias of the 'identifiers' directive and deprecated. | |
510 | ||
46347502 MW |
511 | doc: *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 | ||
46347502 MW |
523 | Without options, the kernel-doc directive includes all documentation comments |
524 | from the source file. | |
525 | ||
526 | The 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 | |
529 | source. | |
530 | ||
531 | .. _kernel_doc: | |
93626d7a MCC |
532 | |
533 | How to use kernel-doc to generate man pages | |
534 | ------------------------------------------- | |
535 | ||
536 | If you just want to use kernel-doc to generate man pages you can do this | |
5b229fbe | 537 | from the kernel git tree:: |
93626d7a | 538 | |
7d1179f0 FR |
539 | $ scripts/kernel-doc -man \ |
540 | $(git grep -l '/\*\*' -- :^Documentation :^tools) \ | |
541 | | scripts/split-man.pl /tmp/man | |
542 | ||
543 | Some older versions of git do not support some of the variants of syntax for | |
544 | path 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 |