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 | |
46 | kernel-doc comments can be either "*/" or "**/". | |
47 | ||
48 | Kernel-doc comments should be placed just before the function | |
49 | or data structure being described. | |
50 | ||
51 | Example kernel-doc function comment: | |
52 | ||
53 | /** | |
54 | * foobar() - short function description of foobar | |
55 | * @arg1: Describe the first argument to foobar. | |
56 | * @arg2: Describe the second argument to foobar. | |
57 | * One can provide multiple line descriptions | |
58 | * for arguments. | |
59 | * | |
60 | * A longer description, with more discussion of the function foobar() | |
61 | * that might be useful to those using or modifying it. Begins with | |
62 | * empty comment line, and may include additional embedded empty | |
63 | * comment lines. | |
64 | * | |
65 | * The longer description can have multiple paragraphs. | |
66 | **/ | |
67 | ||
68 | The first line, with the short description, must be on a single line. | |
69 | ||
70 | The @argument descriptions must begin on the very next line following | |
71 | this opening short function description line, with no intervening | |
72 | empty comment lines. | |
73 | ||
74 | Example kernel-doc data structure comment. | |
75 | ||
76 | /** | |
77 | * struct blah - the basic blah structure | |
78 | * @mem1: describe the first member of struct blah | |
79 | * @mem2: describe the second member of struct blah, | |
80 | * perhaps with more lines and words. | |
81 | * | |
82 | * Longer description of this structure. | |
83 | **/ | |
84 | ||
85 | The kernel-doc function comments describe each parameter to the | |
86 | function, in order, with the @name lines. | |
87 | ||
88 | The kernel-doc data structure comments describe each structure member | |
89 | in the data structure, with the @name lines. | |
90 | ||
91 | The longer description formatting is "reflowed", losing your line | |
92 | breaks. So presenting carefully formatted lists within these | |
93 | descriptions won't work so well; derived documentation will lose | |
94 | the formatting. | |
95 | ||
96 | See the section below "How to add extractable documentation to your | |
97 | source files" for more details and notes on how to format kernel-doc | |
98 | comments. | |
99 | ||
100 | Components of the kernel-doc system | |
101 | ----------------------------------- | |
102 | ||
1da177e4 LT |
103 | Many places in the source tree have extractable documentation in the |
104 | form of block comments above functions. The components of this system | |
105 | are: | |
106 | ||
107 | - scripts/kernel-doc | |
108 | ||
109 | This is a perl script that hunts for the block comments and can mark | |
110 | them up directly into DocBook, man, text, and HTML. (No, not | |
111 | texinfo.) | |
112 | ||
113 | - Documentation/DocBook/*.tmpl | |
114 | ||
115 | These are SGML template files, which are normal SGML files with | |
116 | special place-holders for where the extracted documentation should | |
117 | go. | |
118 | ||
c6120938 | 119 | - scripts/basic/docproc.c |
1da177e4 LT |
120 | |
121 | This is a program for converting SGML template files into SGML | |
122 | files. When a file is referenced it is searched for symbols | |
123 | exported (EXPORT_SYMBOL), to be able to distinguish between internal | |
124 | and external functions. | |
125 | It invokes kernel-doc, giving it the list of functions that | |
126 | are to be documented. | |
127 | Additionally it is used to scan the SGML template files to locate | |
128 | all the files referenced herein. This is used to generate dependency | |
129 | information as used by make. | |
130 | ||
131 | - Makefile | |
132 | ||
133 | The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used | |
134 | to build DocBook files, PostScript files, PDF files, and html files | |
135 | in Documentation/DocBook. | |
136 | ||
137 | - Documentation/DocBook/Makefile | |
138 | ||
139 | This is where C files are associated with SGML templates. | |
140 | ||
141 | ||
142 | How to extract the documentation | |
143 | -------------------------------- | |
144 | ||
145 | If you just want to read the ready-made books on the various | |
146 | subsystems (see Documentation/DocBook/*.tmpl), just type 'make | |
d28bee0c RD |
147 | psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your |
148 | preference. If you would rather read a different format, you can type | |
149 | 'make sgmldocs' and then use DocBook tools to convert | |
150 | Documentation/DocBook/*.sgml to a format of your choice (for example, | |
1da177e4 LT |
151 | 'db2html ...' if 'make htmldocs' was not defined). |
152 | ||
153 | If you want to see man pages instead, you can do this: | |
154 | ||
155 | $ cd linux | |
156 | $ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man | |
157 | $ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man | |
158 | ||
159 | Here is split-man.pl: | |
160 | ||
161 | --> | |
162 | #!/usr/bin/perl | |
163 | ||
164 | if ($#ARGV < 0) { | |
165 | die "where do I put the results?\n"; | |
166 | } | |
167 | ||
168 | mkdir $ARGV[0],0777; | |
169 | $state = 0; | |
170 | while (<STDIN>) { | |
171 | if (/^\.TH \"[^\"]*\" 4 \"([^\"]*)\"/) { | |
172 | if ($state == 1) { close OUT } | |
173 | $state = 1; | |
174 | $fn = "$ARGV[0]/$1.4"; | |
175 | print STDERR "Creating $fn\n"; | |
176 | open OUT, ">$fn" or die "can't open $fn: $!\n"; | |
177 | print OUT $_; | |
178 | } elsif ($state != 0) { | |
179 | print OUT $_; | |
180 | } | |
181 | } | |
182 | ||
183 | close OUT; | |
184 | <-- | |
185 | ||
186 | If you just want to view the documentation for one function in one | |
187 | file, you can do this: | |
188 | ||
189 | $ scripts/kernel-doc -man -function fn file | nroff -man | less | |
190 | ||
191 | or this: | |
192 | ||
193 | $ scripts/kernel-doc -text -function fn file | |
194 | ||
195 | ||
196 | How to add extractable documentation to your source files | |
197 | --------------------------------------------------------- | |
198 | ||
199 | The format of the block comment is like this: | |
200 | ||
201 | /** | |
202 | * function_name(:)? (- short description)? | |
891dcd2f | 203 | (* @parameterx(space)*: (description of parameter x)?)* |
1da177e4 LT |
204 | (* a blank line)? |
205 | * (Description:)? (Description of function)? | |
206 | * (section header: (section description)? )* | |
207 | (*)?*/ | |
208 | ||
262086cf RD |
209 | The short function description ***cannot be multiline***, but the other |
210 | descriptions can be (and they can contain blank lines). If you continue | |
211 | that initial short description onto a second line, that second line will | |
212 | appear further down at the beginning of the description section, which is | |
213 | almost certainly not what you had in mind. | |
214 | ||
215 | Avoid putting a spurious blank line after the function name, or else the | |
216 | description will be repeated! | |
1da177e4 LT |
217 | |
218 | All descriptive text is further processed, scanning for the following special | |
219 | patterns, which are highlighted appropriately. | |
220 | ||
221 | 'funcname()' - function | |
222 | '$ENVVAR' - environment variable | |
223 | '&struct_name' - name of a structure (up to two words including 'struct') | |
224 | '@parameter' - name of a parameter | |
225 | '%CONST' - name of a constant. | |
226 | ||
262086cf RD |
227 | NOTE 1: The multi-line descriptive text you provide does *not* recognize |
228 | line breaks, so if you try to format some text nicely, as in: | |
229 | ||
230 | Return codes | |
231 | 0 - cool | |
232 | 1 - invalid arg | |
233 | 2 - out of memory | |
234 | ||
235 | this will all run together and produce: | |
236 | ||
237 | Return codes 0 - cool 1 - invalid arg 2 - out of memory | |
238 | ||
239 | NOTE 2: If the descriptive text you provide has lines that begin with | |
240 | some phrase followed by a colon, each of those phrases will be taken as | |
241 | a new section heading, which means you should similarly try to avoid text | |
242 | like: | |
243 | ||
244 | Return codes: | |
245 | 0: cool | |
246 | 1: invalid arg | |
247 | 2: out of memory | |
248 | ||
249 | every line of which would start a new section. Again, probably not | |
250 | what you were after. | |
251 | ||
1da177e4 LT |
252 | Take a look around the source tree for examples. |
253 | ||
254 | ||
d28bee0c RD |
255 | kernel-doc for structs, unions, enums, and typedefs |
256 | --------------------------------------------------- | |
257 | ||
258 | Beside functions you can also write documentation for structs, unions, | |
259 | enums and typedefs. Instead of the function name you must write the name | |
260 | of the declaration; the struct/union/enum/typedef must always precede | |
261 | the name. Nesting of declarations is not supported. | |
262 | Use the argument mechanism to document members or constants. | |
263 | ||
264 | Inside a struct description, you can use the "private:" and "public:" | |
265 | comment tags. Structure fields that are inside a "private:" area | |
266 | are not listed in the generated output documentation. | |
267 | ||
268 | Example: | |
269 | ||
270 | /** | |
271 | * struct my_struct - short description | |
272 | * @a: first member | |
273 | * @b: second member | |
274 | * | |
275 | * Longer description | |
276 | */ | |
277 | struct my_struct { | |
278 | int a; | |
279 | int b; | |
280 | /* private: */ | |
281 | int c; | |
282 | }; | |
283 | ||
284 | ||
1da177e4 LT |
285 | How to make new SGML template files |
286 | ----------------------------------- | |
287 | ||
288 | SGML template files (*.tmpl) are like normal SGML files, except that | |
289 | they can contain escape sequences where extracted documentation should | |
290 | be inserted. | |
291 | ||
292 | !E<filename> is replaced by the documentation, in <filename>, for | |
293 | functions that are exported using EXPORT_SYMBOL: the function list is | |
294 | collected from files listed in Documentation/DocBook/Makefile. | |
295 | ||
296 | !I<filename> is replaced by the documentation for functions that are | |
297 | _not_ exported using EXPORT_SYMBOL. | |
298 | ||
299 | !D<filename> is used to name additional files to search for functions | |
300 | exported using EXPORT_SYMBOL. | |
301 | ||
302 | !F<filename> <function [functions...]> is replaced by the | |
303 | documentation, in <filename>, for the functions listed. | |
304 | ||
305 | ||
306 | Tim. | |
307 | */ <twaugh@redhat.com> |