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