Merge tag 'drm-misc-next-2019-04-10' of git://anongit.freedesktop.org/drm/drm-misc...
[sfrench/cifs-2.6.git] / Documentation / doc-guide / kernel-doc.rst
1 Writing kernel-doc comments
2 ===========================
3
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.
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
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.
18
19 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
20
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.
25
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.
32
33 How to format kernel-doc comments
34 ---------------------------------
35
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.
40
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.
46
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
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    *
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 function_name.
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
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
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
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
165      as a new section heading, which probably won't produce the desired
166      effect.
167
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.
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
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.
186
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 ~~~~~~~
193
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
225 Nested structs/unions
226 ~~~~~~~~~~~~~~~~~~~~~
227
228 It 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
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;
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
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.
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
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
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
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
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
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:
451
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*.
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
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
479 doc: *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
491 functions: *[ function ...]*
492   Include documentation for each *function* in *source*.
493   If no *function* is specified, the documentation for all functions
494   and types in the *source* will be included.
495
496   Examples::
497
498     .. kernel-doc:: lib/bitmap.c
499        :functions: bitmap_parselist bitmap_parselist_user
500
501     .. kernel-doc:: lib/idr.c
502        :functions:
503
504 Without options, the kernel-doc directive includes all documentation comments
505 from the source file.
506
507 The kernel-doc extension is included in the kernel source tree, at
508 ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
509 ``scripts/kernel-doc`` script to extract the documentation comments from the
510 source.
511
512 .. _kernel_doc:
513
514 How to use kernel-doc to generate man pages
515 -------------------------------------------
516
517 If you just want to use kernel-doc to generate man pages you can do this
518 from the kernel git tree::
519
520   $ scripts/kernel-doc -man \
521     $(git grep -l '/\*\*' -- :^Documentation :^tools) \
522     | scripts/split-man.pl /tmp/man
523
524 Some older versions of git do not support some of the variants of syntax for
525 path exclusion.  One of the following commands may work for those versions::
526
527   $ scripts/kernel-doc -man \
528     $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
529     | scripts/split-man.pl /tmp/man
530
531   $ scripts/kernel-doc -man \
532     $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
533     | scripts/split-man.pl /tmp/man