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