Root/
1 | kernel-doc nano-HOWTO |
2 | ===================== |
3 | |
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 |
46 | kernel-doc comments can be either "*/" or "**/", but "*/" is |
47 | preferred in the Linux kernel tree. |
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. |
67 | * |
68 | * Return: Describe the return value of foobar. |
69 | */ |
70 | |
71 | The short description following the subject can span multiple lines |
72 | and ends with an @argument description, an empty line or the end of |
73 | the comment block. |
74 | |
75 | The @argument descriptions must begin on the very next line following |
76 | this opening short function description line, with no intervening |
77 | empty comment lines. |
78 | |
79 | If a function parameter is "..." (varargs), it should be listed in |
80 | kernel-doc notation as: |
81 | * @...: description |
82 | |
83 | The return value, if any, should be described in a dedicated section |
84 | named "Return". |
85 | |
86 | Example kernel-doc data structure comment. |
87 | |
88 | /** |
89 | * struct blah - the basic blah structure |
90 | * @mem1: describe the first member of struct blah |
91 | * @mem2: describe the second member of struct blah, |
92 | * perhaps with more lines and words. |
93 | * |
94 | * Longer description of this structure. |
95 | */ |
96 | |
97 | The kernel-doc function comments describe each parameter to the |
98 | function, in order, with the @name lines. |
99 | |
100 | The kernel-doc data structure comments describe each structure member |
101 | in the data structure, with the @name lines. |
102 | |
103 | The longer description formatting is "reflowed", losing your line |
104 | breaks. So presenting carefully formatted lists within these |
105 | descriptions won't work so well; derived documentation will lose |
106 | the formatting. |
107 | |
108 | See the section below "How to add extractable documentation to your |
109 | source files" for more details and notes on how to format kernel-doc |
110 | comments. |
111 | |
112 | Components of the kernel-doc system |
113 | ----------------------------------- |
114 | |
115 | Many places in the source tree have extractable documentation in the |
116 | form of block comments above functions. The components of this system |
117 | are: |
118 | |
119 | - scripts/kernel-doc |
120 | |
121 | This is a perl script that hunts for the block comments and can mark |
122 | them up directly into DocBook, man, text, and HTML. (No, not |
123 | texinfo.) |
124 | |
125 | - Documentation/DocBook/*.tmpl |
126 | |
127 | These are SGML template files, which are normal SGML files with |
128 | special place-holders for where the extracted documentation should |
129 | go. |
130 | |
131 | - scripts/basic/docproc.c |
132 | |
133 | This is a program for converting SGML template files into SGML |
134 | files. When a file is referenced it is searched for symbols |
135 | exported (EXPORT_SYMBOL), to be able to distinguish between internal |
136 | and external functions. |
137 | It invokes kernel-doc, giving it the list of functions that |
138 | are to be documented. |
139 | Additionally it is used to scan the SGML template files to locate |
140 | all the files referenced herein. This is used to generate dependency |
141 | information as used by make. |
142 | |
143 | - Makefile |
144 | |
145 | The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used |
146 | to build DocBook files, PostScript files, PDF files, and html files |
147 | in Documentation/DocBook. |
148 | |
149 | - Documentation/DocBook/Makefile |
150 | |
151 | This is where C files are associated with SGML templates. |
152 | |
153 | |
154 | How to extract the documentation |
155 | -------------------------------- |
156 | |
157 | If you just want to read the ready-made books on the various |
158 | subsystems (see Documentation/DocBook/*.tmpl), just type 'make |
159 | psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your |
160 | preference. If you would rather read a different format, you can type |
161 | 'make sgmldocs' and then use DocBook tools to convert |
162 | Documentation/DocBook/*.sgml to a format of your choice (for example, |
163 | 'db2html ...' if 'make htmldocs' was not defined). |
164 | |
165 | If you want to see man pages instead, you can do this: |
166 | |
167 | $ cd linux |
168 | $ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man |
169 | $ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man |
170 | |
171 | Here is split-man.pl: |
172 | |
173 | --> |
174 | #!/usr/bin/perl |
175 | |
176 | if ($#ARGV < 0) { |
177 | die "where do I put the results?\n"; |
178 | } |
179 | |
180 | mkdir $ARGV[0],0777; |
181 | $state = 0; |
182 | while (<STDIN>) { |
183 | if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { |
184 | if ($state == 1) { close OUT } |
185 | $state = 1; |
186 | $fn = "$ARGV[0]/$1.9"; |
187 | print STDERR "Creating $fn\n"; |
188 | open OUT, ">$fn" or die "can't open $fn: $!\n"; |
189 | print OUT $_; |
190 | } elsif ($state != 0) { |
191 | print OUT $_; |
192 | } |
193 | } |
194 | |
195 | close OUT; |
196 | <-- |
197 | |
198 | If you just want to view the documentation for one function in one |
199 | file, you can do this: |
200 | |
201 | $ scripts/kernel-doc -man -function fn file | nroff -man | less |
202 | |
203 | or this: |
204 | |
205 | $ scripts/kernel-doc -text -function fn file |
206 | |
207 | |
208 | How to add extractable documentation to your source files |
209 | --------------------------------------------------------- |
210 | |
211 | The format of the block comment is like this: |
212 | |
213 | /** |
214 | * function_name(:)? (- short description)? |
215 | (* @parameterx(space)*: (description of parameter x)?)* |
216 | (* a blank line)? |
217 | * (Description:)? (Description of function)? |
218 | * (section header: (section description)? )* |
219 | (*)?*/ |
220 | |
221 | All "description" text can span multiple lines, although the |
222 | function_name & its short description are traditionally on a single line. |
223 | Description text may also contain blank lines (i.e., lines that contain |
224 | only a "*"). |
225 | |
226 | "section header:" names must be unique per function (or struct, |
227 | union, typedef, enum). |
228 | |
229 | Use the section header "Return" for sections describing the return value |
230 | of a function. |
231 | |
232 | Avoid putting a spurious blank line after the function name, or else the |
233 | description will be repeated! |
234 | |
235 | All descriptive text is further processed, scanning for the following special |
236 | patterns, which are highlighted appropriately. |
237 | |
238 | 'funcname()' - function |
239 | '$ENVVAR' - environment variable |
240 | '&struct_name' - name of a structure (up to two words including 'struct') |
241 | '@parameter' - name of a parameter |
242 | '%CONST' - name of a constant. |
243 | |
244 | NOTE 1: The multi-line descriptive text you provide does *not* recognize |
245 | line breaks, so if you try to format some text nicely, as in: |
246 | |
247 | Return: |
248 | 0 - cool |
249 | 1 - invalid arg |
250 | 2 - out of memory |
251 | |
252 | this will all run together and produce: |
253 | |
254 | Return: 0 - cool 1 - invalid arg 2 - out of memory |
255 | |
256 | NOTE 2: 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 as |
258 | a new section heading, which means you should similarly try to avoid text |
259 | like: |
260 | |
261 | Return: |
262 | 0: cool |
263 | 1: invalid arg |
264 | 2: out of memory |
265 | |
266 | every line of which would start a new section. Again, probably not |
267 | what you were after. |
268 | |
269 | Take a look around the source tree for examples. |
270 | |
271 | |
272 | kernel-doc for structs, unions, enums, and typedefs |
273 | --------------------------------------------------- |
274 | |
275 | Beside functions you can also write documentation for structs, unions, |
276 | enums and typedefs. Instead of the function name you must write the name |
277 | of the declaration; the struct/union/enum/typedef must always precede |
278 | the name. Nesting of declarations is not supported. |
279 | Use the argument mechanism to document members or constants. |
280 | |
281 | Inside a struct description, you can use the "private:" and "public:" |
282 | comment tags. Structure fields that are inside a "private:" area |
283 | are not listed in the generated output documentation. The "private:" |
284 | and "public:" tags must begin immediately following a "/*" comment |
285 | marker. They may optionally include comments between the ":" and the |
286 | ending "*/" marker. |
287 | |
288 | Example: |
289 | |
290 | /** |
291 | * struct my_struct - short description |
292 | * @a: first member |
293 | * @b: second member |
294 | * |
295 | * Longer description |
296 | */ |
297 | struct my_struct { |
298 | int a; |
299 | int b; |
300 | /* private: internal use only */ |
301 | int c; |
302 | }; |
303 | |
304 | |
305 | Including documentation blocks in source files |
306 | ---------------------------------------------- |
307 | |
308 | To facilitate having source code and comments close together, you can |
309 | include kernel-doc documentation blocks that are free-form comments |
310 | instead of being kernel-doc for functions, structures, unions, |
311 | enums, or typedefs. This could be used for something like a |
312 | theory of operation for a driver or library code, for example. |
313 | |
314 | This is done by using a DOC: section keyword with a section title. E.g.: |
315 | |
316 | /** |
317 | * DOC: Theory of Operation |
318 | * |
319 | * The whizbang foobar is a dilly of a gizmo. It can do whatever you |
320 | * want it to do, at any time. It reads your mind. Here's how it works. |
321 | * |
322 | * foo bar splat |
323 | * |
324 | * The only drawback to this gizmo is that is can sometimes damage |
325 | * hardware, software, or its subject(s). |
326 | */ |
327 | |
328 | DOC: sections are used in SGML templates files as indicated below. |
329 | |
330 | |
331 | How to make new SGML template files |
332 | ----------------------------------- |
333 | |
334 | SGML template files (*.tmpl) are like normal SGML files, except that |
335 | they can contain escape sequences where extracted documentation should |
336 | be inserted. |
337 | |
338 | !E<filename> is replaced by the documentation, in <filename>, for |
339 | functions that are exported using EXPORT_SYMBOL: the function list is |
340 | collected from files listed in Documentation/DocBook/Makefile. |
341 | |
342 | !I<filename> is replaced by the documentation for functions that are |
343 | _not_ exported using EXPORT_SYMBOL. |
344 | |
345 | !D<filename> is used to name additional files to search for functions |
346 | exported using EXPORT_SYMBOL. |
347 | |
348 | !F<filename> <function [functions...]> is replaced by the |
349 | documentation, in <filename>, for the functions listed. |
350 | |
351 | !P<filename> <section title> is replaced by the contents of the DOC: |
352 | section titled <section title> from <filename>. |
353 | Spaces are allowed in <section title>; do not quote the <section title>. |
354 | |
355 | !C<filename> is replaced by nothing, but makes the tools check that |
356 | all DOC: sections and documented functions, symbols, etc. are used. |
357 | This makes sense to use when you use !F/!P only and want to verify |
358 | that all documentation is included. |
359 | |
360 | Tim. |
361 | */ <twaugh@redhat.com> |
362 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9