blob: 104740ea0041266b00d4efcaaeb7c5b30dd79c75 [file] [log] [blame]
Jonathan Corbet8ed292f2016-07-20 16:43:41 -06001NOTE: this document is outdated and will eventually be removed. See
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -02002Documentation/doc-guide/ for current information.
Jonathan Corbet8ed292f2016-07-20 16:43:41 -06003
Linus Torvalds1da177e2005-04-16 15:20:36 -07004kernel-doc nano-HOWTO
5=====================
6
Paul Jackson0842b242008-06-05 22:46:45 -07007How to format kernel-doc comments
8---------------------------------
9
10In order to provide embedded, 'C' friendly, easy to maintain,
11but consistent and extractable documentation of the functions and
12data structures in the Linux kernel, the Linux kernel has adopted
13a consistent style for documenting functions and their parameters,
14and structures and their members.
15
16The format for this documentation is called the kernel-doc format.
17It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
18
19This style embeds the documentation within the source files, using
20a few simple conventions. The scripts/kernel-doc perl script, some
21SGML templates in Documentation/DocBook, and other tools understand
22these conventions, and are used to extract this embedded documentation
23into various documents.
24
25In order to provide good documentation of kernel functions and data
26structures, please use the following conventions to format your
27kernel-doc comments in Linux kernel source.
28
29We definitely need kernel-doc formatted documentation for functions
30that are exported to loadable modules using EXPORT_SYMBOL.
31
32We also look to provide kernel-doc formatted documentation for
33functions externally visible to other kernel files (not marked
34"static").
35
36We also recommend providing kernel-doc formatted documentation
37for private (file "static") routines, for consistency of kernel
38source code layout. But this is lower priority and at the
39discretion of the MAINTAINER of that kernel source file.
40
41Data structures visible in kernel include files should also be
42documented using kernel-doc formatted comments.
43
44The opening comment mark "/**" is reserved for kernel-doc comments.
45Only comments so marked will be considered by the kernel-doc scripts,
46and any comment so marked must be in kernel-doc format. Do not use
47"/**" to be begin a comment block unless the comment block contains
48kernel-doc formatted comments. The closing comment marker for
Randy Dunlapf40b45a2009-02-11 13:04:31 -080049kernel-doc comments can be either "*/" or "**/", but "*/" is
50preferred in the Linux kernel tree.
Paul Jackson0842b242008-06-05 22:46:45 -070051
52Kernel-doc comments should be placed just before the function
53or data structure being described.
54
55Example kernel-doc function comment:
56
57/**
58 * foobar() - short function description of foobar
59 * @arg1: Describe the first argument to foobar.
60 * @arg2: Describe the second argument to foobar.
61 * One can provide multiple line descriptions
62 * for arguments.
63 *
64 * A longer description, with more discussion of the function foobar()
65 * that might be useful to those using or modifying it. Begins with
66 * empty comment line, and may include additional embedded empty
67 * comment lines.
68 *
69 * The longer description can have multiple paragraphs.
Yacine Belkadie65fe5a2012-11-26 22:21:23 +010070 *
71 * Return: Describe the return value of foobar.
Randy Dunlapf40b45a2009-02-11 13:04:31 -080072 */
Paul Jackson0842b242008-06-05 22:46:45 -070073
Johannes Weiner64231332009-09-17 19:26:53 -070074The short description following the subject can span multiple lines
75and ends with an @argument description, an empty line or the end of
76the comment block.
Paul Jackson0842b242008-06-05 22:46:45 -070077
78The @argument descriptions must begin on the very next line following
79this opening short function description line, with no intervening
80empty comment lines.
81
Randy Dunlapd78dd072009-01-06 14:42:40 -080082If a function parameter is "..." (varargs), it should be listed in
83kernel-doc notation as:
84 * @...: description
85
Yacine Belkadie65fe5a2012-11-26 22:21:23 +010086The return value, if any, should be described in a dedicated section
87named "Return".
Randy Dunlapd78dd072009-01-06 14:42:40 -080088
Paul Jackson0842b242008-06-05 22:46:45 -070089Example kernel-doc data structure comment.
90
91/**
92 * struct blah - the basic blah structure
93 * @mem1: describe the first member of struct blah
94 * @mem2: describe the second member of struct blah,
95 * perhaps with more lines and words.
96 *
97 * Longer description of this structure.
Randy Dunlapf40b45a2009-02-11 13:04:31 -080098 */
Paul Jackson0842b242008-06-05 22:46:45 -070099
100The kernel-doc function comments describe each parameter to the
101function, in order, with the @name lines.
102
103The kernel-doc data structure comments describe each structure member
104in the data structure, with the @name lines.
105
106The longer description formatting is "reflowed", losing your line
107breaks. So presenting carefully formatted lists within these
108descriptions won't work so well; derived documentation will lose
109the formatting.
110
111See the section below "How to add extractable documentation to your
112source files" for more details and notes on how to format kernel-doc
113comments.
114
115Components of the kernel-doc system
116-----------------------------------
117
Linus Torvalds1da177e2005-04-16 15:20:36 -0700118Many places in the source tree have extractable documentation in the
119form of block comments above functions. The components of this system
120are:
121
122- scripts/kernel-doc
123
124 This is a perl script that hunts for the block comments and can mark
125 them up directly into DocBook, man, text, and HTML. (No, not
126 texinfo.)
127
128- Documentation/DocBook/*.tmpl
129
130 These are SGML template files, which are normal SGML files with
131 special place-holders for where the extracted documentation should
132 go.
133
Peter Hueweacc068d2015-07-13 22:02:48 +0200134- scripts/docproc.c
Linus Torvalds1da177e2005-04-16 15:20:36 -0700135
136 This is a program for converting SGML template files into SGML
137 files. When a file is referenced it is searched for symbols
138 exported (EXPORT_SYMBOL), to be able to distinguish between internal
139 and external functions.
140 It invokes kernel-doc, giving it the list of functions that
141 are to be documented.
142 Additionally it is used to scan the SGML template files to locate
143 all the files referenced herein. This is used to generate dependency
144 information as used by make.
145
146- Makefile
147
Robert P. J. Day01462c22013-05-02 11:27:03 -0400148 The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
149 to build XML DocBook files, PostScript files, PDF files, and html files
150 in Documentation/DocBook. The older target 'sgmldocs' is equivalent
151 to 'xmldocs'.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700152
153- Documentation/DocBook/Makefile
154
155 This is where C files are associated with SGML templates.
156
157
158How to extract the documentation
159--------------------------------
160
161If you just want to read the ready-made books on the various
162subsystems (see Documentation/DocBook/*.tmpl), just type 'make
Randy Dunlapd28bee02006-02-01 03:06:57 -0800163psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
164preference. If you would rather read a different format, you can type
Robert P. J. Day01462c22013-05-02 11:27:03 -0400165'make xmldocs' and then use DocBook tools to convert
166Documentation/DocBook/*.xml to a format of your choice (for example,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700167'db2html ...' if 'make htmldocs' was not defined).
168
169If you want to see man pages instead, you can do this:
170
171$ cd linux
172$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
173$ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man
174
175Here is split-man.pl:
176
177-->
178#!/usr/bin/perl
179
180if ($#ARGV < 0) {
181 die "where do I put the results?\n";
182}
183
184mkdir $ARGV[0],0777;
185$state = 0;
186while (<STDIN>) {
Kevin Diggs65eb3dc2008-08-26 10:26:54 +0200187 if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700188 if ($state == 1) { close OUT }
189 $state = 1;
Kevin Diggs65eb3dc2008-08-26 10:26:54 +0200190 $fn = "$ARGV[0]/$1.9";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700191 print STDERR "Creating $fn\n";
192 open OUT, ">$fn" or die "can't open $fn: $!\n";
193 print OUT $_;
194 } elsif ($state != 0) {
195 print OUT $_;
196 }
197}
198
199close OUT;
200<--
201
202If you just want to view the documentation for one function in one
203file, you can do this:
204
205$ scripts/kernel-doc -man -function fn file | nroff -man | less
206
207or this:
208
209$ scripts/kernel-doc -text -function fn file
210
211
212How to add extractable documentation to your source files
213---------------------------------------------------------
214
215The format of the block comment is like this:
216
217/**
218 * function_name(:)? (- short description)?
Randy Dunlap891dcd22007-02-10 01:45:53 -0800219(* @parameterx(space)*: (description of parameter x)?)*
Linus Torvalds1da177e2005-04-16 15:20:36 -0700220(* a blank line)?
221 * (Description:)? (Description of function)?
222 * (section header: (section description)? )*
223(*)?*/
224
Randy Dunlapd2b34e22010-01-08 14:43:09 -0800225All "description" text can span multiple lines, although the
226function_name & its short description are traditionally on a single line.
227Description text may also contain blank lines (i.e., lines that contain
228only a "*").
229
230"section header:" names must be unique per function (or struct,
231union, typedef, enum).
Robert P. J. Day262086c2007-02-10 01:45:58 -0800232
Yacine Belkadie65fe5a2012-11-26 22:21:23 +0100233Use the section header "Return" for sections describing the return value
234of a function.
235
Robert P. J. Day262086c2007-02-10 01:45:58 -0800236Avoid putting a spurious blank line after the function name, or else the
237description will be repeated!
Linus Torvalds1da177e2005-04-16 15:20:36 -0700238
239All descriptive text is further processed, scanning for the following special
240patterns, which are highlighted appropriately.
241
242'funcname()' - function
243'$ENVVAR' - environment variable
244'&struct_name' - name of a structure (up to two words including 'struct')
245'@parameter' - name of a parameter
246'%CONST' - name of a constant.
247
Robert P. J. Day262086c2007-02-10 01:45:58 -0800248NOTE 1: The multi-line descriptive text you provide does *not* recognize
249line breaks, so if you try to format some text nicely, as in:
250
Yacine Belkadie65fe5a2012-11-26 22:21:23 +0100251 Return:
Robert P. J. Day262086c2007-02-10 01:45:58 -0800252 0 - cool
253 1 - invalid arg
254 2 - out of memory
255
256this will all run together and produce:
257
Yacine Belkadie65fe5a2012-11-26 22:21:23 +0100258 Return: 0 - cool 1 - invalid arg 2 - out of memory
Robert P. J. Day262086c2007-02-10 01:45:58 -0800259
260NOTE 2: If the descriptive text you provide has lines that begin with
261some phrase followed by a colon, each of those phrases will be taken as
262a new section heading, which means you should similarly try to avoid text
263like:
264
Yacine Belkadie65fe5a2012-11-26 22:21:23 +0100265 Return:
Robert P. J. Day262086c2007-02-10 01:45:58 -0800266 0: cool
267 1: invalid arg
268 2: out of memory
269
270every line of which would start a new section. Again, probably not
271what you were after.
272
Linus Torvalds1da177e2005-04-16 15:20:36 -0700273Take a look around the source tree for examples.
274
275
Randy Dunlapd28bee02006-02-01 03:06:57 -0800276kernel-doc for structs, unions, enums, and typedefs
277---------------------------------------------------
278
279Beside functions you can also write documentation for structs, unions,
280enums and typedefs. Instead of the function name you must write the name
281of the declaration; the struct/union/enum/typedef must always precede
282the name. Nesting of declarations is not supported.
283Use the argument mechanism to document members or constants.
284
285Inside a struct description, you can use the "private:" and "public:"
286comment tags. Structure fields that are inside a "private:" area
Randy Dunlap52dc5ae2009-04-30 15:08:53 -0700287are not listed in the generated output documentation. The "private:"
288and "public:" tags must begin immediately following a "/*" comment
289marker. They may optionally include comments between the ":" and the
290ending "*/" marker.
Randy Dunlapd28bee02006-02-01 03:06:57 -0800291
292Example:
293
294/**
295 * struct my_struct - short description
296 * @a: first member
297 * @b: second member
298 *
299 * Longer description
300 */
301struct my_struct {
302 int a;
303 int b;
Randy Dunlap52dc5ae2009-04-30 15:08:53 -0700304/* private: internal use only */
Randy Dunlapd28bee02006-02-01 03:06:57 -0800305 int c;
306};
307
308
Randy Dunlap28f4d752009-01-06 14:42:43 -0800309Including documentation blocks in source files
310----------------------------------------------
311
312To facilitate having source code and comments close together, you can
313include kernel-doc documentation blocks that are free-form comments
314instead of being kernel-doc for functions, structures, unions,
315enums, or typedefs. This could be used for something like a
316theory of operation for a driver or library code, for example.
317
318This is done by using a DOC: section keyword with a section title. E.g.:
319
320/**
321 * DOC: Theory of Operation
322 *
323 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
324 * want it to do, at any time. It reads your mind. Here's how it works.
325 *
326 * foo bar splat
327 *
328 * The only drawback to this gizmo is that is can sometimes damage
329 * hardware, software, or its subject(s).
330 */
331
332DOC: sections are used in SGML templates files as indicated below.
333
334
Linus Torvalds1da177e2005-04-16 15:20:36 -0700335How to make new SGML template files
336-----------------------------------
337
338SGML template files (*.tmpl) are like normal SGML files, except that
339they can contain escape sequences where extracted documentation should
340be inserted.
341
342!E<filename> is replaced by the documentation, in <filename>, for
343functions that are exported using EXPORT_SYMBOL: the function list is
344collected from files listed in Documentation/DocBook/Makefile.
345
346!I<filename> is replaced by the documentation for functions that are
347_not_ exported using EXPORT_SYMBOL.
348
349!D<filename> is used to name additional files to search for functions
350exported using EXPORT_SYMBOL.
351
352!F<filename> <function [functions...]> is replaced by the
353documentation, in <filename>, for the functions listed.
354
Randy Dunlap28f4d752009-01-06 14:42:43 -0800355!P<filename> <section title> is replaced by the contents of the DOC:
356section titled <section title> from <filename>.
357Spaces are allowed in <section title>; do not quote the <section title>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700358
Johannes Bergeda603f2010-09-11 15:55:22 -0700359!C<filename> is replaced by nothing, but makes the tools check that
360all DOC: sections and documented functions, symbols, etc. are used.
361This makes sense to use when you use !F/!P only and want to verify
362that all documentation is included.
363
Linus Torvalds1da177e2005-04-16 15:20:36 -0700364Tim.
365*/ <twaugh@redhat.com>