]>
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. | |
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 | ||
123 | The format is similar for documentation for structures, enums, paragraphs, | |
124 | etc. See the sections below for details. | |
125 | ||
126 | The kernel-doc structure is extracted from the comments, and proper `Sphinx C | |
127 | Domain`_ function and type descriptions with anchors are generated for them. The | |
128 | descriptions are filtered for special kernel-doc highlights and | |
129 | cross-references. See below for details. | |
130 | ||
131 | .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html | |
132 | ||
133 | Highlights and cross-references | |
134 | ------------------------------- | |
135 | ||
136 | The following special patterns are recognized in the kernel-doc comment | |
137 | descriptive text and converted to proper reStructuredText markup and `Sphinx C | |
138 | Domain`_ 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 | ||
5d47c31b MCC |
152 | ````literal```` |
153 | A literal block that should be handled as-is. The output will use a | |
154 | ``monospaced font``. | |
155 | ||
156 | Useful if you need to use special characters that would otherwise have some | |
157 | meaning either by kernel-doc script of by reStructuredText. | |
158 | ||
159 | This is particularly useful if you need to use things like ``%ph`` inside | |
160 | a function description. | |
161 | ||
17defc28 JN |
162 | ``$ENVVAR`` |
163 | Name of an environment variable. (No cross-referencing, just formatting.) | |
164 | ||
165 | ``&struct name`` | |
166 | Structure reference. | |
167 | ||
168 | ``&enum name`` | |
169 | Enum reference. | |
170 | ||
171 | ``&typedef name`` | |
172 | Typedef reference. | |
173 | ||
174 | ``&struct_name->member`` or ``&struct_name.member`` | |
175 | Structure or union member reference. The cross-reference will be to the struct | |
176 | or union definition, not the member directly. | |
177 | ||
178 | ``&name`` | |
179 | A generic type reference. Prefer using the full reference described above | |
180 | instead. This is mostly for legacy comments. | |
181 | ||
182 | Cross-referencing from reStructuredText | |
183 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
184 | ||
185 | To cross-reference the functions and types defined in the kernel-doc comments | |
186 | from reStructuredText documents, please use the `Sphinx C Domain`_ | |
187 | references. For example:: | |
188 | ||
189 | See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. | |
190 | ||
191 | While the type reference works with just the type name, without the | |
192 | struct/union/enum/typedef part in front, you may want to use:: | |
193 | ||
194 | See :c:type:`struct foo <foo>`. | |
195 | See :c:type:`union bar <bar>`. | |
196 | See :c:type:`enum baz <baz>`. | |
197 | See :c:type:`typedef meh <meh>`. | |
198 | ||
199 | This will produce prettier links, and is in line with how kernel-doc does the | |
200 | cross-references. | |
201 | ||
202 | For further details, please refer to the `Sphinx C Domain`_ documentation. | |
203 | ||
204 | Function documentation | |
205 | ---------------------- | |
206 | ||
207 | The general format of a function and function-like macro kernel-doc comment is:: | |
208 | ||
209 | /** | |
210 | * function_name() - Brief description of function. | |
211 | * @arg1: Describe the first argument. | |
212 | * @arg2: Describe the second argument. | |
213 | * One can provide multiple line descriptions | |
214 | * for arguments. | |
215 | * | |
216 | * A longer description, with more discussion of the function function_name() | |
217 | * that might be useful to those using or modifying it. Begins with an | |
218 | * empty comment line, and may include additional embedded empty | |
219 | * comment lines. | |
220 | * | |
221 | * The longer description may have multiple paragraphs. | |
222 | * | |
223 | * Return: Describe the return value of foobar. | |
224 | * | |
225 | * The return value description can also have multiple paragraphs, and should | |
226 | * be placed at the end of the comment block. | |
227 | */ | |
228 | ||
229 | The brief description following the function name may span multiple lines, and | |
230 | ends with an ``@argument:`` description, a blank comment line, or the end of the | |
231 | comment block. | |
232 | ||
233 | The kernel-doc function comments describe each parameter to the function, in | |
234 | order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions | |
235 | must begin on the very next line following the opening brief function | |
236 | description line, with no intervening blank comment lines. The ``@argument:`` | |
237 | descriptions may span multiple lines. The continuation lines may contain | |
238 | indentation. If a function parameter is ``...`` (varargs), it should be listed | |
239 | in kernel-doc notation as: ``@...:``. | |
240 | ||
241 | The return value, if any, should be described in a dedicated section at the end | |
242 | of the comment starting with "Return:". | |
243 | ||
244 | Structure, union, and enumeration documentation | |
245 | ----------------------------------------------- | |
246 | ||
247 | The general format of a struct, union, and enum kernel-doc comment is:: | |
248 | ||
249 | /** | |
250 | * struct struct_name - Brief description. | |
251 | * @member_name: Description of member member_name. | |
252 | * | |
253 | * Description of the structure. | |
254 | */ | |
255 | ||
256 | Below, "struct" is used to mean structs, unions and enums, and "member" is used | |
257 | to mean struct and union members as well as enumerations in an enum. | |
258 | ||
259 | The brief description following the structure name may span multiple lines, and | |
260 | ends with a ``@member:`` description, a blank comment line, or the end of the | |
261 | comment block. | |
262 | ||
263 | The kernel-doc data structure comments describe each member of the structure, in | |
264 | order, with the ``@member:`` descriptions. The ``@member:`` descriptions must | |
265 | begin on the very next line following the opening brief function description | |
266 | line, with no intervening blank comment lines. The ``@member:`` descriptions may | |
267 | span multiple lines. The continuation lines may contain indentation. | |
268 | ||
269 | In-line member documentation comments | |
270 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
271 | ||
38f985e3 DV |
272 | The structure members may also be documented in-line within the definition. |
273 | There are two styles, single-line comments where both the opening ``/**`` and | |
274 | closing ``*/`` are on the same line, and multi-line comments where they are each | |
275 | on a line of their own, like all other kernel-doc comments:: | |
17defc28 JN |
276 | |
277 | /** | |
278 | * struct foo - Brief description. | |
279 | * @foo: The Foo member. | |
280 | */ | |
281 | struct foo { | |
282 | int foo; | |
283 | /** | |
284 | * @bar: The Bar member. | |
285 | */ | |
286 | int bar; | |
287 | /** | |
288 | * @baz: The Baz member. | |
289 | * | |
290 | * Here, the member description may contain several paragraphs. | |
291 | */ | |
292 | int baz; | |
38f985e3 DV |
293 | /** @foobar: Single line description. */ |
294 | int foobar; | |
17defc28 JN |
295 | } |
296 | ||
297 | Private members | |
298 | ~~~~~~~~~~~~~~~ | |
299 | ||
300 | Inside a struct description, you can use the "private:" and "public:" comment | |
301 | tags. Structure fields that are inside a "private:" area are not listed in the | |
302 | generated output documentation. The "private:" and "public:" tags must begin | |
303 | immediately following a ``/*`` comment marker. They may optionally include | |
304 | comments between the ``:`` and the ending ``*/`` marker. | |
305 | ||
306 | Example:: | |
307 | ||
308 | /** | |
309 | * struct my_struct - short description | |
310 | * @a: first member | |
311 | * @b: second member | |
312 | * | |
313 | * Longer description | |
314 | */ | |
315 | struct my_struct { | |
316 | int a; | |
317 | int b; | |
318 | /* private: internal use only */ | |
319 | int c; | |
320 | }; | |
321 | ||
322 | ||
323 | Typedef documentation | |
324 | --------------------- | |
325 | ||
326 | The general format of a typedef kernel-doc comment is:: | |
327 | ||
328 | /** | |
329 | * typedef type_name - Brief description. | |
330 | * | |
331 | * Description of the type. | |
332 | */ | |
333 | ||
334 | Overview documentation comments | |
335 | ------------------------------- | |
336 | ||
337 | To facilitate having source code and comments close together, you can include | |
338 | kernel-doc documentation blocks that are free-form comments instead of being | |
339 | kernel-doc for functions, structures, unions, enums, or typedefs. This could be | |
340 | used for something like a theory of operation for a driver or library code, for | |
341 | example. | |
342 | ||
343 | This is done by using a ``DOC:`` section keyword with a section title. | |
344 | ||
345 | The general format of an overview or high-level documentation comment is:: | |
346 | ||
347 | /** | |
348 | * DOC: Theory of Operation | |
349 | * | |
350 | * The whizbang foobar is a dilly of a gizmo. It can do whatever you | |
351 | * want it to do, at any time. It reads your mind. Here's how it works. | |
352 | * | |
353 | * foo bar splat | |
354 | * | |
355 | * The only drawback to this gizmo is that is can sometimes damage | |
356 | * hardware, software, or its subject(s). | |
357 | */ | |
358 | ||
359 | The title following ``DOC:`` acts as a heading within the source file, but also | |
360 | as an identifier for extracting the documentation comment. Thus, the title must | |
361 | be unique within the file. | |
362 | ||
363 | Recommendations | |
364 | --------------- | |
365 | ||
366 | We definitely need kernel-doc formatted documentation for functions that are | |
367 | exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. | |
368 | ||
369 | We also look to provide kernel-doc formatted documentation for functions | |
370 | externally visible to other kernel files (not marked "static"). | |
371 | ||
372 | We also recommend providing kernel-doc formatted documentation for private (file | |
373 | "static") routines, for consistency of kernel source code layout. But this is | |
374 | lower priority and at the discretion of the MAINTAINER of that kernel source | |
375 | file. | |
376 | ||
377 | Data structures visible in kernel include files should also be documented using | |
378 | kernel-doc formatted comments. |