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