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