blob: 2fb7f2bfc2455b72a0f390f259587c2d6ceaa299 [file] [log] [blame]
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -02001Writing kernel-doc comments
2===========================
3
Matthew Wilcox46347502018-02-13 13:15:37 -08004The Linux kernel source files may contain structured documentation
5comments in the kernel-doc format to describe the functions, types
6and design of the code. It is easier to keep documentation up-to-date
7when it is embedded in source files.
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -02008
Matthew Wilcox46347502018-02-13 13:15:37 -08009.. 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.
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -020013
Matthew Wilcox46347502018-02-13 13:15:37 -080014The kernel-doc structure is extracted from the comments, and proper
15`Sphinx C Domain`_ function and type descriptions with anchors are
16generated from them. The descriptions are filtered for special kernel-doc
17highlights and cross-references. See below for details.
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -020018
Matthew Wilcox46347502018-02-13 13:15:37 -080019.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
20
21Every function that is exported to loadable modules using
22``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
23comment. Functions and data structures in header files which are intended
24to be used by modules should also have kernel-doc comments.
25
26It is good practice to also provide kernel-doc formatted documentation
27for functions externally visible to other kernel files (not marked
28``static``). We also recommend providing kernel-doc formatted
29documentation for private (file ``static``) routines, for consistency of
30kernel source code layout. This is lower priority and at the discretion
31of the maintainer of that kernel source file.
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -020032
33How to format kernel-doc comments
34---------------------------------
35
Matthew Wilcox46347502018-02-13 13:15:37 -080036The opening comment mark ``/**`` is used for kernel-doc comments. The
37``kernel-doc`` tool will extract comments marked this way. The rest of
38the comment is formatted like a normal multi-line comment with a column
39of asterisks on the left side, closing with ``*/`` on a line by itself.
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -020040
Matthew Wilcox46347502018-02-13 13:15:37 -080041The function and type kernel-doc comments should be placed just before
42the function or type being described in order to maximise the chance
43that somebody changing the code will also change the documentation. The
44overview kernel-doc comments may be placed anywhere at the top indentation
45level.
Mauro Carvalho Chehab01f2c182017-12-18 10:30:03 -020046
Mauro Carvalho Chehabfc275bf2017-12-18 10:30:04 -020047Function documentation
48----------------------
49
50The general format of a function and function-like macro kernel-doc comment is::
51
52 /**
53 * function_name() - Brief description of function.
54 * @arg1: Describe the first argument.
55 * @arg2: Describe the second argument.
56 * One can provide multiple line descriptions
57 * for arguments.
58 *
59 * A longer description, with more discussion of the function function_name()
60 * that might be useful to those using or modifying it. Begins with an
61 * empty comment line, and may include additional embedded empty
62 * comment lines.
63 *
64 * The longer description may have multiple paragraphs.
65 *
Matthew Wilcoxda70b8c2018-02-13 13:15:33 -080066 * Context: Describes whether the function can sleep, what locks it takes,
67 * releases, or expects to be held. It can extend over multiple
68 * lines.
Mauro Carvalho Chehabfc275bf2017-12-18 10:30:04 -020069 * Return: Describe the return value of foobar.
70 *
71 * The return value description can also have multiple paragraphs, and should
72 * be placed at the end of the comment block.
73 */
74
75The brief description following the function name may span multiple lines, and
76ends with an argument description, a blank comment line, or the end of the
77comment block.
78
Matthew Wilcox46347502018-02-13 13:15:37 -080079Function parameters
80~~~~~~~~~~~~~~~~~~~
81
82Each function argument should be described in order, immediately following
83the short function description. Do not leave a blank line between the
84function description and the arguments, nor between the arguments.
85
86Each ``@argument:`` description may span multiple lines.
87
88.. note::
89
90 If the ``@argument`` description has multiple lines, the continuation
91 of the description should start at the same column as the previous line::
92
93 * @argument: some long description
94 * that continues on next lines
95
96 or::
97
98 * @argument:
99 * some long description
100 * that continues on next lines
101
102If a function has a variable number of arguments, its description should
103be written in kernel-doc notation as::
104
105 * @...: description
106
Matthew Wilcoxda70b8c2018-02-13 13:15:33 -0800107Function context
108~~~~~~~~~~~~~~~~
109
110The context in which a function can be called should be described in a
111section named ``Context``. This should include whether the function
112sleeps or can be called from interrupt context, as well as what locks
113it takes, releases and expects to be held by its caller.
114
115Examples::
116
117 * Context: Any context.
118 * Context: Any context. Takes and releases the RCU lock.
119 * Context: Any context. Expects <lock> to be held by caller.
120 * Context: Process context. May sleep if @gfp flags permit.
121 * Context: Process context. Takes and releases <mutex>.
122 * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
123 * Context: Interrupt context.
124
Mauro Carvalho Chehabfc275bf2017-12-18 10:30:04 -0200125Return values
126~~~~~~~~~~~~~
127
128The return value, if any, should be described in a dedicated section
129named ``Return``.
130
131.. note::
132
133 #) The multi-line descriptive text you provide does *not* recognize
134 line breaks, so if you try to format some text nicely, as in::
135
136 * Return:
137 * 0 - OK
138 * -EINVAL - invalid argument
139 * -ENOMEM - out of memory
140
141 this will all run together and produce::
142
143 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
144
145 So, in order to produce the desired line breaks, you need to use a
146 ReST list, e. g.::
147
148 * Return:
149 * * 0 - OK to runtime suspend the device
150 * * -EBUSY - Device should not be runtime suspended
151
152 #) If the descriptive text you provide has lines that begin with
153 some phrase followed by a colon, each of those phrases will be taken
Matthew Wilcoxdcb50d92018-02-13 13:15:34 -0800154 as a new section heading, which probably won't produce the desired
Mauro Carvalho Chehabfc275bf2017-12-18 10:30:04 -0200155 effect.
156
Mauro Carvalho Chehab553aa3c2017-12-18 10:30:05 -0200157Structure, union, and enumeration documentation
158-----------------------------------------------
159
160The general format of a struct, union, and enum kernel-doc comment is::
161
162 /**
163 * struct struct_name - Brief description.
Matthew Wilcox46347502018-02-13 13:15:37 -0800164 * @member1: Description of member1.
165 * @member2: Description of member2.
166 * One can provide multiple line descriptions
167 * for members.
Mauro Carvalho Chehab553aa3c2017-12-18 10:30:05 -0200168 *
169 * Description of the structure.
170 */
171
Matthew Wilcox46347502018-02-13 13:15:37 -0800172You can replace the ``struct`` in the above example with ``union`` or
173``enum`` to describe unions or enums. ``member`` is used to mean struct
174and union member names as well as enumerations in an enum.
Mauro Carvalho Chehab553aa3c2017-12-18 10:30:05 -0200175
Matthew Wilcox46347502018-02-13 13:15:37 -0800176The brief description following the structure name may span multiple
177lines, and ends with a member description, a blank comment line, or the
178end of the comment block.
Mauro Carvalho Chehab553aa3c2017-12-18 10:30:05 -0200179
Matthew Wilcox46347502018-02-13 13:15:37 -0800180Members
181~~~~~~~
182
183Members of structs, unions and enums should be documented the same way
184as function parameters; they immediately succeed the short description
185and may be multi-line.
186
187Inside a struct or union description, you can use the ``private:`` and
188``public:`` comment tags. Structure fields that are inside a ``private:``
189area are not listed in the generated output documentation.
190
191The ``private:`` and ``public:`` tags must begin immediately following a
192``/*`` comment marker. They may optionally include comments between the
193``:`` and the ending ``*/`` marker.
194
195Example::
196
197 /**
198 * struct my_struct - short description
199 * @a: first member
200 * @b: second member
201 * @d: fourth member
202 *
203 * Longer description
204 */
205 struct my_struct {
206 int a;
207 int b;
208 /* private: internal use only */
209 int c;
210 /* public: the next one is public */
211 int d;
212 };
213
214In-line member documentation comments
215~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
216
217The structure members may also be documented in-line within the definition.
218There are two styles, single-line comments where both the opening ``/**`` and
219closing ``*/`` are on the same line, and multi-line comments where they are each
220on a line of their own, like all other kernel-doc comments::
221
222 /**
223 * struct foo - Brief description.
224 * @foo: The Foo member.
225 */
226 struct foo {
227 int foo;
228 /**
229 * @bar: The Bar member.
230 */
231 int bar;
232 /**
233 * @baz: The Baz member.
234 *
235 * Here, the member description may contain several paragraphs.
236 */
237 int baz;
238 /** @foobar: Single line description. */
239 int foobar;
240 }
Mauro Carvalho Chehab553aa3c2017-12-18 10:30:05 -0200241
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200242Nested structs/unions
243~~~~~~~~~~~~~~~~~~~~~
244
Matthew Wilcox46347502018-02-13 13:15:37 -0800245It is possible to document nested structs and unions, like::
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200246
247 /**
248 * struct nested_foobar - a struct with nested unions and structs
Matthew Wilcox46347502018-02-13 13:15:37 -0800249 * @memb1: first member of anonymous union/anonymous struct
250 * @memb2: second member of anonymous union/anonymous struct
251 * @memb3: third member of anonymous union/anonymous struct
252 * @memb4: fourth member of anonymous union/anonymous struct
253 * @bar.st1.memb1: first member of struct st1 on union bar
254 * @bar.st1.memb2: second member of struct st1 on union bar
255 * @bar.st2.memb1: first member of struct st2 on union bar
256 * @bar.st2.memb2: second member of struct st2 on union bar
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200257 struct nested_foobar {
258 /* Anonymous union/struct*/
259 union {
260 struct {
Matthew Wilcox46347502018-02-13 13:15:37 -0800261 int memb1;
262 int memb2;
Matthew Wilcoxdcb50d92018-02-13 13:15:34 -0800263 }
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200264 struct {
Matthew Wilcox46347502018-02-13 13:15:37 -0800265 void *memb3;
266 int memb4;
Matthew Wilcoxdcb50d92018-02-13 13:15:34 -0800267 }
268 }
269 union {
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200270 struct {
Matthew Wilcox46347502018-02-13 13:15:37 -0800271 int memb1;
272 int memb2;
Matthew Wilcoxdcb50d92018-02-13 13:15:34 -0800273 } st1;
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200274 struct {
Matthew Wilcox46347502018-02-13 13:15:37 -0800275 void *memb1;
276 int memb2;
Matthew Wilcoxdcb50d92018-02-13 13:15:34 -0800277 } st2;
278 } bar;
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200279 };
280
281.. note::
282
283 #) When documenting nested structs or unions, if the struct/union ``foo``
Matthew Wilcox46347502018-02-13 13:15:37 -0800284 is named, the member ``bar`` inside it should be documented as
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200285 ``@foo.bar:``
Matthew Wilcox46347502018-02-13 13:15:37 -0800286 #) When the nested struct/union is anonymous, the member ``bar`` in it
Mauro Carvalho Chehab8ad72162017-12-18 10:30:13 -0200287 should be documented as ``@bar:``
Mauro Carvalho Chehab553aa3c2017-12-18 10:30:05 -0200288
Mauro Carvalho Chehabbdb76f92017-12-18 10:30:06 -0200289Typedef documentation
290---------------------
291
292The general format of a typedef kernel-doc comment is::
293
294 /**
295 * typedef type_name - Brief description.
296 *
297 * Description of the type.
298 */
299
300Typedefs with function prototypes can also be documented::
301
302 /**
303 * typedef type_name - Brief description.
304 * @arg1: description of arg1
305 * @arg2: description of arg2
306 *
307 * Description of the type.
Matthew Wilcoxda70b8c2018-02-13 13:15:33 -0800308 *
309 * Context: Locking context.
310 * Return: Meaning of the return value.
Mauro Carvalho Chehabbdb76f92017-12-18 10:30:06 -0200311 */
312 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
313
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -0200314Highlights and cross-references
315-------------------------------
316
317The following special patterns are recognized in the kernel-doc comment
318descriptive text and converted to proper reStructuredText markup and `Sphinx C
319Domain`_ references.
320
321.. attention:: The below are **only** recognized within kernel-doc comments,
322 **not** within normal reStructuredText documents.
323
324``funcname()``
325 Function reference.
326
327``@parameter``
328 Name of a function parameter. (No cross-referencing, just formatting.)
329
330``%CONST``
331 Name of a constant. (No cross-referencing, just formatting.)
332
Mauro Carvalho Chehab5d47c312017-05-16 08:17:49 -0300333````literal````
334 A literal block that should be handled as-is. The output will use a
335 ``monospaced font``.
336
337 Useful if you need to use special characters that would otherwise have some
338 meaning either by kernel-doc script of by reStructuredText.
339
340 This is particularly useful if you need to use things like ``%ph`` inside
341 a function description.
342
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -0200343``$ENVVAR``
344 Name of an environment variable. (No cross-referencing, just formatting.)
345
346``&struct name``
347 Structure reference.
348
349``&enum name``
350 Enum reference.
351
352``&typedef name``
353 Typedef reference.
354
355``&struct_name->member`` or ``&struct_name.member``
356 Structure or union member reference. The cross-reference will be to the struct
357 or union definition, not the member directly.
358
359``&name``
360 A generic type reference. Prefer using the full reference described above
361 instead. This is mostly for legacy comments.
362
363Cross-referencing from reStructuredText
364~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
365
366To cross-reference the functions and types defined in the kernel-doc comments
367from reStructuredText documents, please use the `Sphinx C Domain`_
368references. For example::
369
370 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
371
372While the type reference works with just the type name, without the
373struct/union/enum/typedef part in front, you may want to use::
374
375 See :c:type:`struct foo <foo>`.
376 See :c:type:`union bar <bar>`.
377 See :c:type:`enum baz <baz>`.
378 See :c:type:`typedef meh <meh>`.
379
380This will produce prettier links, and is in line with how kernel-doc does the
381cross-references.
382
383For further details, please refer to the `Sphinx C Domain`_ documentation.
384
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -0200385Overview documentation comments
386-------------------------------
387
388To facilitate having source code and comments close together, you can include
389kernel-doc documentation blocks that are free-form comments instead of being
390kernel-doc for functions, structures, unions, enums, or typedefs. This could be
391used for something like a theory of operation for a driver or library code, for
392example.
393
394This is done by using a ``DOC:`` section keyword with a section title.
395
396The general format of an overview or high-level documentation comment is::
397
398 /**
399 * DOC: Theory of Operation
400 *
401 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
402 * want it to do, at any time. It reads your mind. Here's how it works.
403 *
404 * foo bar splat
405 *
406 * The only drawback to this gizmo is that is can sometimes damage
407 * hardware, software, or its subject(s).
408 */
409
410The title following ``DOC:`` acts as a heading within the source file, but also
411as an identifier for extracting the documentation comment. Thus, the title must
412be unique within the file.
413
Matthew Wilcox46347502018-02-13 13:15:37 -0800414Including kernel-doc comments
415=============================
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -0200416
Matthew Wilcox46347502018-02-13 13:15:37 -0800417The documentation comments may be included in any of the reStructuredText
418documents using a dedicated kernel-doc Sphinx directive extension.
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -0200419
Matthew Wilcox46347502018-02-13 13:15:37 -0800420The kernel-doc directive is of the format::
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -0200421
Matthew Wilcox46347502018-02-13 13:15:37 -0800422 .. kernel-doc:: source
423 :option:
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -0200424
Matthew Wilcox46347502018-02-13 13:15:37 -0800425The *source* is the path to a source file, relative to the kernel source
426tree. The following directive options are supported:
427
428export: *[source-pattern ...]*
429 Include documentation for all functions in *source* that have been exported
430 using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
431 of the files specified by *source-pattern*.
432
433 The *source-pattern* is useful when the kernel-doc comments have been placed
434 in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
435 the function definitions.
436
437 Examples::
438
439 .. kernel-doc:: lib/bitmap.c
440 :export:
441
442 .. kernel-doc:: include/net/mac80211.h
443 :export: net/mac80211/*.c
444
445internal: *[source-pattern ...]*
446 Include documentation for all functions and types in *source* that have
447 **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
448 in *source* or in any of the files specified by *source-pattern*.
449
450 Example::
451
452 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
453 :internal:
454
455doc: *title*
456 Include documentation for the ``DOC:`` paragraph identified by *title* in
457 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
458 is only used as an identifier for the paragraph, and is not included in the
459 output. Please make sure to have an appropriate heading in the enclosing
460 reStructuredText document.
461
462 Example::
463
464 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
465 :doc: High Definition Audio over HDMI and Display Port
466
467functions: *function* *[...]*
468 Include documentation for each *function* in *source*.
469
470 Example::
471
472 .. kernel-doc:: lib/bitmap.c
473 :functions: bitmap_parselist bitmap_parselist_user
474
475Without options, the kernel-doc directive includes all documentation comments
476from the source file.
477
478The kernel-doc extension is included in the kernel source tree, at
479``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
480``scripts/kernel-doc`` script to extract the documentation comments from the
481source.
482
483.. _kernel_doc:
Mauro Carvalho Chehab93626d72017-12-18 10:30:07 -0200484
485How to use kernel-doc to generate man pages
486-------------------------------------------
487
488If you just want to use kernel-doc to generate man pages you can do this
Matthew Wilcox5b229fb2018-02-13 13:15:35 -0800489from the kernel git tree::
Mauro Carvalho Chehab93626d72017-12-18 10:30:07 -0200490
Matthew Wilcox5b229fb2018-02-13 13:15:35 -0800491 $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man