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