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