Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | kernel-doc nano-HOWTO |
2 | ===================== | |
3 | ||
0842b245 PJ |
4 | How to format kernel-doc comments |
5 | --------------------------------- | |
6 | ||
7 | In order to provide embedded, 'C' friendly, easy to maintain, | |
8 | but consistent and extractable documentation of the functions and | |
9 | data structures in the Linux kernel, the Linux kernel has adopted | |
10 | a consistent style for documenting functions and their parameters, | |
11 | and structures and their members. | |
12 | ||
13 | The format for this documentation is called the kernel-doc format. | |
14 | It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file. | |
15 | ||
16 | This style embeds the documentation within the source files, using | |
17 | a few simple conventions. The scripts/kernel-doc perl script, some | |
18 | SGML templates in Documentation/DocBook, and other tools understand | |
19 | these conventions, and are used to extract this embedded documentation | |
20 | into various documents. | |
21 | ||
22 | In order to provide good documentation of kernel functions and data | |
23 | structures, please use the following conventions to format your | |
24 | kernel-doc comments in Linux kernel source. | |
25 | ||
26 | We definitely need kernel-doc formatted documentation for functions | |
27 | that are exported to loadable modules using EXPORT_SYMBOL. | |
28 | ||
29 | We also look to provide kernel-doc formatted documentation for | |
30 | functions externally visible to other kernel files (not marked | |
31 | "static"). | |
32 | ||
33 | We also recommend providing kernel-doc formatted documentation | |
34 | for private (file "static") routines, for consistency of kernel | |
35 | source code layout. But this is lower priority and at the | |
36 | discretion of the MAINTAINER of that kernel source file. | |
37 | ||
38 | Data structures visible in kernel include files should also be | |
39 | documented using kernel-doc formatted comments. | |
40 | ||
41 | The opening comment mark "/**" is reserved for kernel-doc comments. | |
42 | Only comments so marked will be considered by the kernel-doc scripts, | |
43 | and any comment so marked must be in kernel-doc format. Do not use | |
44 | "/**" to be begin a comment block unless the comment block contains | |
45 | kernel-doc formatted comments. The closing comment marker for | |
f40b45a2 RD |
46 | kernel-doc comments can be either "*/" or "**/", but "*/" is |
47 | preferred in the Linux kernel tree. | |
0842b245 PJ |
48 | |
49 | Kernel-doc comments should be placed just before the function | |
50 | or data structure being described. | |
51 | ||
52 | Example kernel-doc function comment: | |
53 | ||
54 | /** | |
55 | * foobar() - short function description of foobar | |
56 | * @arg1: Describe the first argument to foobar. | |
57 | * @arg2: Describe the second argument to foobar. | |
58 | * One can provide multiple line descriptions | |
59 | * for arguments. | |
60 | * | |
61 | * A longer description, with more discussion of the function foobar() | |
62 | * that might be useful to those using or modifying it. Begins with | |
63 | * empty comment line, and may include additional embedded empty | |
64 | * comment lines. | |
65 | * | |
66 | * The longer description can have multiple paragraphs. | |
f40b45a2 | 67 | */ |
0842b245 PJ |
68 | |
69 | The first line, with the short description, must be on a single line. | |
70 | ||
71 | The @argument descriptions must begin on the very next line following | |
72 | this opening short function description line, with no intervening | |
73 | empty comment lines. | |
74 | ||
d78dd070 RD |
75 | If a function parameter is "..." (varargs), it should be listed in |
76 | kernel-doc notation as: | |
77 | * @...: description | |
78 | ||
79 | ||
0842b245 PJ |
80 | Example kernel-doc data structure comment. |
81 | ||
82 | /** | |
83 | * struct blah - the basic blah structure | |
84 | * @mem1: describe the first member of struct blah | |
85 | * @mem2: describe the second member of struct blah, | |
86 | * perhaps with more lines and words. | |
87 | * | |
88 | * Longer description of this structure. | |
f40b45a2 | 89 | */ |
0842b245 PJ |
90 | |
91 | The kernel-doc function comments describe each parameter to the | |
92 | function, in order, with the @name lines. | |
93 | ||
94 | The kernel-doc data structure comments describe each structure member | |
95 | in the data structure, with the @name lines. | |
96 | ||
97 | The longer description formatting is "reflowed", losing your line | |
98 | breaks. So presenting carefully formatted lists within these | |
99 | descriptions won't work so well; derived documentation will lose | |
100 | the formatting. | |
101 | ||
102 | See the section below "How to add extractable documentation to your | |
103 | source files" for more details and notes on how to format kernel-doc | |
104 | comments. | |
105 | ||
106 | Components of the kernel-doc system | |
107 | ----------------------------------- | |
108 | ||
1da177e4 LT |
109 | Many places in the source tree have extractable documentation in the |
110 | form of block comments above functions. The components of this system | |
111 | are: | |
112 | ||
113 | - scripts/kernel-doc | |
114 | ||
115 | This is a perl script that hunts for the block comments and can mark | |
116 | them up directly into DocBook, man, text, and HTML. (No, not | |
117 | texinfo.) | |
118 | ||
119 | - Documentation/DocBook/*.tmpl | |
120 | ||
121 | These are SGML template files, which are normal SGML files with | |
122 | special place-holders for where the extracted documentation should | |
123 | go. | |
124 | ||
c6120938 | 125 | - scripts/basic/docproc.c |
1da177e4 LT |
126 | |
127 | This is a program for converting SGML template files into SGML | |
128 | files. When a file is referenced it is searched for symbols | |
129 | exported (EXPORT_SYMBOL), to be able to distinguish between internal | |
130 | and external functions. | |
131 | It invokes kernel-doc, giving it the list of functions that | |
132 | are to be documented. | |
133 | Additionally it is used to scan the SGML template files to locate | |
134 | all the files referenced herein. This is used to generate dependency | |
135 | information as used by make. | |
136 | ||
137 | - Makefile | |
138 | ||
139 | The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used | |
140 | to build DocBook files, PostScript files, PDF files, and html files | |
141 | in Documentation/DocBook. | |
142 | ||
143 | - Documentation/DocBook/Makefile | |
144 | ||
145 | This is where C files are associated with SGML templates. | |
146 | ||
147 | ||
148 | How to extract the documentation | |
149 | -------------------------------- | |
150 | ||
151 | If you just want to read the ready-made books on the various | |
152 | subsystems (see Documentation/DocBook/*.tmpl), just type 'make | |
d28bee0c RD |
153 | psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your |
154 | preference. If you would rather read a different format, you can type | |
155 | 'make sgmldocs' and then use DocBook tools to convert | |
156 | Documentation/DocBook/*.sgml to a format of your choice (for example, | |
1da177e4 LT |
157 | 'db2html ...' if 'make htmldocs' was not defined). |
158 | ||
159 | If you want to see man pages instead, you can do this: | |
160 | ||
161 | $ cd linux | |
162 | $ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man | |
163 | $ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man | |
164 | ||
165 | Here is split-man.pl: | |
166 | ||
167 | --> | |
168 | #!/usr/bin/perl | |
169 | ||
170 | if ($#ARGV < 0) { | |
171 | die "where do I put the results?\n"; | |
172 | } | |
173 | ||
174 | mkdir $ARGV[0],0777; | |
175 | $state = 0; | |
176 | while (<STDIN>) { | |
65eb3dc6 | 177 | if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { |
1da177e4 LT |
178 | if ($state == 1) { close OUT } |
179 | $state = 1; | |
65eb3dc6 | 180 | $fn = "$ARGV[0]/$1.9"; |
1da177e4 LT |
181 | print STDERR "Creating $fn\n"; |
182 | open OUT, ">$fn" or die "can't open $fn: $!\n"; | |
183 | print OUT $_; | |
184 | } elsif ($state != 0) { | |
185 | print OUT $_; | |
186 | } | |
187 | } | |
188 | ||
189 | close OUT; | |
190 | <-- | |
191 | ||
192 | If you just want to view the documentation for one function in one | |
193 | file, you can do this: | |
194 | ||
195 | $ scripts/kernel-doc -man -function fn file | nroff -man | less | |
196 | ||
197 | or this: | |
198 | ||
199 | $ scripts/kernel-doc -text -function fn file | |
200 | ||
201 | ||
202 | How to add extractable documentation to your source files | |
203 | --------------------------------------------------------- | |
204 | ||
205 | The format of the block comment is like this: | |
206 | ||
207 | /** | |
208 | * function_name(:)? (- short description)? | |
891dcd2f | 209 | (* @parameterx(space)*: (description of parameter x)?)* |
1da177e4 LT |
210 | (* a blank line)? |
211 | * (Description:)? (Description of function)? | |
212 | * (section header: (section description)? )* | |
213 | (*)?*/ | |
214 | ||
262086cf RD |
215 | The short function description ***cannot be multiline***, but the other |
216 | descriptions can be (and they can contain blank lines). If you continue | |
217 | that initial short description onto a second line, that second line will | |
218 | appear further down at the beginning of the description section, which is | |
219 | almost certainly not what you had in mind. | |
220 | ||
221 | Avoid putting a spurious blank line after the function name, or else the | |
222 | description will be repeated! | |
1da177e4 LT |
223 | |
224 | All descriptive text is further processed, scanning for the following special | |
225 | patterns, which are highlighted appropriately. | |
226 | ||
227 | 'funcname()' - function | |
228 | '$ENVVAR' - environment variable | |
229 | '&struct_name' - name of a structure (up to two words including 'struct') | |
230 | '@parameter' - name of a parameter | |
231 | '%CONST' - name of a constant. | |
232 | ||
262086cf RD |
233 | NOTE 1: The multi-line descriptive text you provide does *not* recognize |
234 | line breaks, so if you try to format some text nicely, as in: | |
235 | ||
236 | Return codes | |
237 | 0 - cool | |
238 | 1 - invalid arg | |
239 | 2 - out of memory | |
240 | ||
241 | this will all run together and produce: | |
242 | ||
243 | Return codes 0 - cool 1 - invalid arg 2 - out of memory | |
244 | ||
245 | NOTE 2: If the descriptive text you provide has lines that begin with | |
246 | some phrase followed by a colon, each of those phrases will be taken as | |
247 | a new section heading, which means you should similarly try to avoid text | |
248 | like: | |
249 | ||
250 | Return codes: | |
251 | 0: cool | |
252 | 1: invalid arg | |
253 | 2: out of memory | |
254 | ||
255 | every line of which would start a new section. Again, probably not | |
256 | what you were after. | |
257 | ||
1da177e4 LT |
258 | Take a look around the source tree for examples. |
259 | ||
260 | ||
d28bee0c RD |
261 | kernel-doc for structs, unions, enums, and typedefs |
262 | --------------------------------------------------- | |
263 | ||
264 | Beside functions you can also write documentation for structs, unions, | |
265 | enums and typedefs. Instead of the function name you must write the name | |
266 | of the declaration; the struct/union/enum/typedef must always precede | |
267 | the name. Nesting of declarations is not supported. | |
268 | Use the argument mechanism to document members or constants. | |
269 | ||
270 | Inside a struct description, you can use the "private:" and "public:" | |
271 | comment tags. Structure fields that are inside a "private:" area | |
272 | are not listed in the generated output documentation. | |
273 | ||
274 | Example: | |
275 | ||
276 | /** | |
277 | * struct my_struct - short description | |
278 | * @a: first member | |
279 | * @b: second member | |
280 | * | |
281 | * Longer description | |
282 | */ | |
283 | struct my_struct { | |
284 | int a; | |
285 | int b; | |
286 | /* private: */ | |
287 | int c; | |
288 | }; | |
289 | ||
290 | ||
28f4d75a RD |
291 | Including documentation blocks in source files |
292 | ---------------------------------------------- | |
293 | ||
294 | To facilitate having source code and comments close together, you can | |
295 | include kernel-doc documentation blocks that are free-form comments | |
296 | instead of being kernel-doc for functions, structures, unions, | |
297 | enums, or typedefs. This could be used for something like a | |
298 | theory of operation for a driver or library code, for example. | |
299 | ||
300 | This is done by using a DOC: section keyword with a section title. E.g.: | |
301 | ||
302 | /** | |
303 | * DOC: Theory of Operation | |
304 | * | |
305 | * The whizbang foobar is a dilly of a gizmo. It can do whatever you | |
306 | * want it to do, at any time. It reads your mind. Here's how it works. | |
307 | * | |
308 | * foo bar splat | |
309 | * | |
310 | * The only drawback to this gizmo is that is can sometimes damage | |
311 | * hardware, software, or its subject(s). | |
312 | */ | |
313 | ||
314 | DOC: sections are used in SGML templates files as indicated below. | |
315 | ||
316 | ||
1da177e4 LT |
317 | How to make new SGML template files |
318 | ----------------------------------- | |
319 | ||
320 | SGML template files (*.tmpl) are like normal SGML files, except that | |
321 | they can contain escape sequences where extracted documentation should | |
322 | be inserted. | |
323 | ||
324 | !E<filename> is replaced by the documentation, in <filename>, for | |
325 | functions that are exported using EXPORT_SYMBOL: the function list is | |
326 | collected from files listed in Documentation/DocBook/Makefile. | |
327 | ||
328 | !I<filename> is replaced by the documentation for functions that are | |
329 | _not_ exported using EXPORT_SYMBOL. | |
330 | ||
331 | !D<filename> is used to name additional files to search for functions | |
332 | exported using EXPORT_SYMBOL. | |
333 | ||
334 | !F<filename> <function [functions...]> is replaced by the | |
335 | documentation, in <filename>, for the functions listed. | |
336 | ||
28f4d75a RD |
337 | !P<filename> <section title> is replaced by the contents of the DOC: |
338 | section titled <section title> from <filename>. | |
339 | Spaces are allowed in <section title>; do not quote the <section title>. | |
1da177e4 LT |
340 | |
341 | Tim. | |
342 | */ <twaugh@redhat.com> |