Loading...
1Writing kernel-doc comments
2===========================
3
4The 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.
8
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.
13
14The 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.
18
19.. _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.
32
33How to format kernel-doc comments
34---------------------------------
35
36The 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.
40
41The 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.
46
47Running the ``kernel-doc`` tool with increased verbosity and without actual
48output generation may be used to verify proper formatting of the
49documentation comments. For example::
50
51 scripts/kernel-doc -v -none drivers/foo/bar.c
52
53The documentation format is verified by the kernel build when it is
54requested to perform extra gcc checks::
55
56 make W=n
57
58Function documentation
59----------------------
60
61The 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 *
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.
80 * Return: Describe the return value of foobar.
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
86The brief description following the function name may span multiple lines, and
87ends with an argument description, a blank comment line, or the end of the
88comment block.
89
90Function parameters
91~~~~~~~~~~~~~~~~~~~
92
93Each function argument should be described in order, immediately following
94the short function description. Do not leave a blank line between the
95function description and the arguments, nor between the arguments.
96
97Each ``@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
113If a function has a variable number of arguments, its description should
114be written in kernel-doc notation as::
115
116 * @...: description
117
118Function context
119~~~~~~~~~~~~~~~~
120
121The context in which a function can be called should be described in a
122section named ``Context``. This should include whether the function
123sleeps or can be called from interrupt context, as well as what locks
124it takes, releases and expects to be held by its caller.
125
126Examples::
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
136Return values
137~~~~~~~~~~~~~
138
139The return value, if any, should be described in a dedicated section
140named ``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
165 as a new section heading, which probably won't produce the desired
166 effect.
167
168Structure, union, and enumeration documentation
169-----------------------------------------------
170
171The general format of a struct, union, and enum kernel-doc comment is::
172
173 /**
174 * struct struct_name - Brief description.
175 * @member1: Description of member1.
176 * @member2: Description of member2.
177 * One can provide multiple line descriptions
178 * for members.
179 *
180 * Description of the structure.
181 */
182
183You can replace the ``struct`` in the above example with ``union`` or
184``enum`` to describe unions or enums. ``member`` is used to mean struct
185and union member names as well as enumerations in an enum.
186
187The brief description following the structure name may span multiple
188lines, and ends with a member description, a blank comment line, or the
189end of the comment block.
190
191Members
192~~~~~~~
193
194Members of structs, unions and enums should be documented the same way
195as function parameters; they immediately succeed the short description
196and may be multi-line.
197
198Inside a struct or union description, you can use the ``private:`` and
199``public:`` comment tags. Structure fields that are inside a ``private:``
200area are not listed in the generated output documentation.
201
202The ``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
206Example::
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
225Nested structs/unions
226~~~~~~~~~~~~~~~~~~~~~
227
228It is possible to document nested structs and unions, like::
229
230 /**
231 * struct nested_foobar - a struct with nested unions and structs
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
236 * @bar: non-anonymous union
237 * @bar.st1: struct st1 inside @bar
238 * @bar.st2: struct st2 inside @bar
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
243 */
244 struct nested_foobar {
245 /* Anonymous union/struct*/
246 union {
247 struct {
248 int memb1;
249 int memb2;
250 }
251 struct {
252 void *memb3;
253 int memb4;
254 }
255 }
256 union {
257 struct {
258 int memb1;
259 int memb2;
260 } st1;
261 struct {
262 void *memb1;
263 int memb2;
264 } st2;
265 } bar;
266 };
267
268.. note::
269
270 #) When documenting nested structs or unions, if the struct/union ``foo``
271 is named, the member ``bar`` inside it should be documented as
272 ``@foo.bar:``
273 #) When the nested struct/union is anonymous, the member ``bar`` in it
274 should be documented as ``@bar:``
275
276In-line member documentation comments
277~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
278
279The structure members may also be documented in-line within the definition.
280There are two styles, single-line comments where both the opening ``/**`` and
281closing ``*/`` are on the same line, and multi-line comments where they are each
282on 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;
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;
311 };
312
313Typedef documentation
314---------------------
315
316The 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
324Typedefs 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.
332 *
333 * Context: Locking context.
334 * Return: Meaning of the return value.
335 */
336 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
337
338Highlights and cross-references
339-------------------------------
340
341The following special patterns are recognized in the kernel-doc comment
342descriptive text and converted to proper reStructuredText markup and `Sphinx C
343Domain`_ 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
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
362 meaning either by kernel-doc script of by reStructuredText.
363
364 This is particularly useful if you need to use things like ``%ph`` inside
365 a function description.
366
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
387Cross-referencing from reStructuredText
388~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
389
390To cross-reference the functions and types defined in the kernel-doc comments
391from reStructuredText documents, please use the `Sphinx C Domain`_
392references. For example::
393
394 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
395
396While the type reference works with just the type name, without the
397struct/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
404This will produce prettier links, and is in line with how kernel-doc does the
405cross-references.
406
407For further details, please refer to the `Sphinx C Domain`_ documentation.
408
409Overview documentation comments
410-------------------------------
411
412To facilitate having source code and comments close together, you can include
413kernel-doc documentation blocks that are free-form comments instead of being
414kernel-doc for functions, structures, unions, enums, or typedefs. This could be
415used for something like a theory of operation for a driver or library code, for
416example.
417
418This is done by using a ``DOC:`` section keyword with a section title.
419
420The 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
434The title following ``DOC:`` acts as a heading within the source file, but also
435as an identifier for extracting the documentation comment. Thus, the title must
436be unique within the file.
437
438Including kernel-doc comments
439=============================
440
441The documentation comments may be included in any of the reStructuredText
442documents using a dedicated kernel-doc Sphinx directive extension.
443
444The kernel-doc directive is of the format::
445
446 .. kernel-doc:: source
447 :option:
448
449The *source* is the path to a source file, relative to the kernel source
450tree. The following directive options are supported:
451
452export: *[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*.
456
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.
460
461 Examples::
462
463 .. kernel-doc:: lib/bitmap.c
464 :export:
465
466 .. kernel-doc:: include/net/mac80211.h
467 :export: net/mac80211/*.c
468
469internal: *[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
479doc: *title*
480 Include documentation for the ``DOC:`` paragraph identified by *title* in
481 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
482 is only used as an identifier for the paragraph, and is not included in the
483 output. Please make sure to have an appropriate heading in the enclosing
484 reStructuredText document.
485
486 Example::
487
488 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
489 :doc: High Definition Audio over HDMI and Display Port
490
491functions: *function* *[...]*
492 Include documentation for each *function* in *source*.
493
494 Example::
495
496 .. kernel-doc:: lib/bitmap.c
497 :functions: bitmap_parselist bitmap_parselist_user
498
499Without options, the kernel-doc directive includes all documentation comments
500from the source file.
501
502The kernel-doc extension is included in the kernel source tree, at
503``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
504``scripts/kernel-doc`` script to extract the documentation comments from the
505source.
506
507.. _kernel_doc:
508
509How to use kernel-doc to generate man pages
510-------------------------------------------
511
512If you just want to use kernel-doc to generate man pages you can do this
513from the kernel git tree::
514
515 $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
1Including kernel-doc comments
2=============================
3
4The Linux kernel source files may contain structured documentation comments, or
5kernel-doc comments to describe the functions and types and design of the
6code. The documentation comments may be included to any of the reStructuredText
7documents using a dedicated kernel-doc Sphinx directive extension.
8
9The kernel-doc directive is of the format::
10
11 .. kernel-doc:: source
12 :option:
13
14The *source* is the path to a source file, relative to the kernel source
15tree. The following directive options are supported:
16
17export: *[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
34internal: *[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
44doc: *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
56functions: *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
64Without options, the kernel-doc directive includes all documentation comments
65from the source file.
66
67The kernel-doc extension is included in the kernel source tree, at
68``Documentation/sphinx/kernel-doc.py``. Internally, it uses the
69``scripts/kernel-doc`` script to extract the documentation comments from the
70source.
71
72.. _kernel_doc:
73
74Writing kernel-doc comments
75===========================
76
77In order to provide embedded, "C" friendly, easy to maintain, but consistent and
78extractable overview, function and type documentation, the Linux kernel has
79adopted a consistent style for documentation comments. The format for this
80documentation is called the kernel-doc format, described below. This style
81embeds the documentation within the source files, using a few simple conventions
82for adding documentation paragraphs and documenting functions and their
83parameters, 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
90The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
91the documentation build to extract this embedded documentation into the various
92HTML, PDF, and other format documents.
93
94In order to provide good documentation of kernel functions and data structures,
95please use the following conventions to format your kernel-doc comments in the
96Linux kernel source.
97
98How to format kernel-doc comments
99---------------------------------
100
101The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
102comments so marked will be considered by the ``kernel-doc`` tool. Use it only
103for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
104should be used as the closing comment marker. The lines in between should be
105prefixed by `` * `` (space star space).
106
107The function and type kernel-doc comments should be placed just before the
108function or type being described. The overview kernel-doc comments may be freely
109placed at the top indentation level.
110
111Example kernel-doc function comment::
112
113 /**
114 * foobar() - Brief description of foobar.
115 * @arg: Description of argument of foobar.
116 *
117 * Longer description of foobar.
118 *
119 * Return: Description of return value of foobar.
120 */
121 int foobar(int arg)
122
123The format is similar for documentation for structures, enums, paragraphs,
124etc. See the sections below for details.
125
126The kernel-doc structure is extracted from the comments, and proper `Sphinx C
127Domain`_ function and type descriptions with anchors are generated for them. The
128descriptions are filtered for special kernel-doc highlights and
129cross-references. See below for details.
130
131.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
132
133Highlights and cross-references
134-------------------------------
135
136The following special patterns are recognized in the kernel-doc comment
137descriptive text and converted to proper reStructuredText markup and `Sphinx C
138Domain`_ references.
139
140.. attention:: The below are **only** recognized within kernel-doc comments,
141 **not** within normal reStructuredText documents.
142
143``funcname()``
144 Function reference.
145
146``@parameter``
147 Name of a function parameter. (No cross-referencing, just formatting.)
148
149``%CONST``
150 Name of a constant. (No cross-referencing, just formatting.)
151
152``$ENVVAR``
153 Name of an environment variable. (No cross-referencing, just formatting.)
154
155``&struct name``
156 Structure reference.
157
158``&enum name``
159 Enum reference.
160
161``&typedef name``
162 Typedef reference.
163
164``&struct_name->member`` or ``&struct_name.member``
165 Structure or union member reference. The cross-reference will be to the struct
166 or union definition, not the member directly.
167
168``&name``
169 A generic type reference. Prefer using the full reference described above
170 instead. This is mostly for legacy comments.
171
172Cross-referencing from reStructuredText
173~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
174
175To cross-reference the functions and types defined in the kernel-doc comments
176from reStructuredText documents, please use the `Sphinx C Domain`_
177references. For example::
178
179 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
180
181While the type reference works with just the type name, without the
182struct/union/enum/typedef part in front, you may want to use::
183
184 See :c:type:`struct foo <foo>`.
185 See :c:type:`union bar <bar>`.
186 See :c:type:`enum baz <baz>`.
187 See :c:type:`typedef meh <meh>`.
188
189This will produce prettier links, and is in line with how kernel-doc does the
190cross-references.
191
192For further details, please refer to the `Sphinx C Domain`_ documentation.
193
194Function documentation
195----------------------
196
197The general format of a function and function-like macro kernel-doc comment is::
198
199 /**
200 * function_name() - Brief description of function.
201 * @arg1: Describe the first argument.
202 * @arg2: Describe the second argument.
203 * One can provide multiple line descriptions
204 * for arguments.
205 *
206 * A longer description, with more discussion of the function function_name()
207 * that might be useful to those using or modifying it. Begins with an
208 * empty comment line, and may include additional embedded empty
209 * comment lines.
210 *
211 * The longer description may have multiple paragraphs.
212 *
213 * Return: Describe the return value of foobar.
214 *
215 * The return value description can also have multiple paragraphs, and should
216 * be placed at the end of the comment block.
217 */
218
219The brief description following the function name may span multiple lines, and
220ends with an ``@argument:`` description, a blank comment line, or the end of the
221comment block.
222
223The kernel-doc function comments describe each parameter to the function, in
224order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
225must begin on the very next line following the opening brief function
226description line, with no intervening blank comment lines. The ``@argument:``
227descriptions may span multiple lines. The continuation lines may contain
228indentation. If a function parameter is ``...`` (varargs), it should be listed
229in kernel-doc notation as: ``@...:``.
230
231The return value, if any, should be described in a dedicated section at the end
232of the comment starting with "Return:".
233
234Structure, union, and enumeration documentation
235-----------------------------------------------
236
237The general format of a struct, union, and enum kernel-doc comment is::
238
239 /**
240 * struct struct_name - Brief description.
241 * @member_name: Description of member member_name.
242 *
243 * Description of the structure.
244 */
245
246Below, "struct" is used to mean structs, unions and enums, and "member" is used
247to mean struct and union members as well as enumerations in an enum.
248
249The brief description following the structure name may span multiple lines, and
250ends with a ``@member:`` description, a blank comment line, or the end of the
251comment block.
252
253The kernel-doc data structure comments describe each member of the structure, in
254order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
255begin on the very next line following the opening brief function description
256line, with no intervening blank comment lines. The ``@member:`` descriptions may
257span multiple lines. The continuation lines may contain indentation.
258
259In-line member documentation comments
260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
261
262The structure members may also be documented in-line within the definition.
263There are two styles, single-line comments where both the opening ``/**`` and
264closing ``*/`` are on the same line, and multi-line comments where they are each
265on a line of their own, like all other kernel-doc comments::
266
267 /**
268 * struct foo - Brief description.
269 * @foo: The Foo member.
270 */
271 struct foo {
272 int foo;
273 /**
274 * @bar: The Bar member.
275 */
276 int bar;
277 /**
278 * @baz: The Baz member.
279 *
280 * Here, the member description may contain several paragraphs.
281 */
282 int baz;
283 /** @foobar: Single line description. */
284 int foobar;
285 }
286
287Private members
288~~~~~~~~~~~~~~~
289
290Inside a struct description, you can use the "private:" and "public:" comment
291tags. Structure fields that are inside a "private:" area are not listed in the
292generated output documentation. The "private:" and "public:" tags must begin
293immediately following a ``/*`` comment marker. They may optionally include
294comments between the ``:`` and the ending ``*/`` marker.
295
296Example::
297
298 /**
299 * struct my_struct - short description
300 * @a: first member
301 * @b: second member
302 *
303 * Longer description
304 */
305 struct my_struct {
306 int a;
307 int b;
308 /* private: internal use only */
309 int c;
310 };
311
312
313Typedef documentation
314---------------------
315
316The 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
324Overview documentation comments
325-------------------------------
326
327To facilitate having source code and comments close together, you can include
328kernel-doc documentation blocks that are free-form comments instead of being
329kernel-doc for functions, structures, unions, enums, or typedefs. This could be
330used for something like a theory of operation for a driver or library code, for
331example.
332
333This is done by using a ``DOC:`` section keyword with a section title.
334
335The general format of an overview or high-level documentation comment is::
336
337 /**
338 * DOC: Theory of Operation
339 *
340 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
341 * want it to do, at any time. It reads your mind. Here's how it works.
342 *
343 * foo bar splat
344 *
345 * The only drawback to this gizmo is that is can sometimes damage
346 * hardware, software, or its subject(s).
347 */
348
349The title following ``DOC:`` acts as a heading within the source file, but also
350as an identifier for extracting the documentation comment. Thus, the title must
351be unique within the file.
352
353Recommendations
354---------------
355
356We definitely need kernel-doc formatted documentation for functions that are
357exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
358
359We also look to provide kernel-doc formatted documentation for functions
360externally visible to other kernel files (not marked "static").
361
362We also recommend providing kernel-doc formatted documentation for private (file
363"static") routines, for consistency of kernel source code layout. But this is
364lower priority and at the discretion of the MAINTAINER of that kernel source
365file.
366
367Data structures visible in kernel include files should also be documented using
368kernel-doc formatted comments.