Merge tag 'leds_for_4.17-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/j...
[muen/linux.git] / Documentation / doc-guide / kernel-doc.rst
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
68 ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
69 ``scripts/kernel-doc`` script to extract the documentation comments from the
70 source.
71
72 .. _kernel_doc:
73
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    * @argument1: Description of parameter argument1 of foobar.
116    * @argument2: Description of parameter argument2 of foobar.
117    *
118    * Longer description of foobar.
119    *
120    * Return: Description of return value of foobar.
121    */
122   int foobar(int argument1, char *argument2)
123
124 The format is similar for documentation for structures, enums, paragraphs,
125 etc. See the sections below for specific details of each type.
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
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
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
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
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
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:``
330
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
353
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
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
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
425
426
427 In-line member documentation comments
428 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
429
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::
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;
451         /** @foobar: Single line description. */
452         int foobar;
453   }
454
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.
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;