Based on kernel version 4.15. Page generated on 2018-01-29 10:00 EST.
1 NOTE: this document is outdated and will eventually be removed. See 2 Documentation/doc-guide/ 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, the 21 Documentation/sphinx/kerneldoc.py Sphinx extension 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, ReST, man, text, and HTML. (No, not 126 texinfo.) 127 128 - scripts/docproc.c 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 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/. 145 146 How to extract the documentation 147 -------------------------------- 148 149 If you just want to read the ready-made books on the various 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, 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>) { 174 if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { 175 if ($state == 1) { close OUT } 176 $state = 1; 177 $fn = "$ARGV[0]/$1.9"; 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)? 206 (* @parameterx(space)*: (description of parameter x)?)* 207 (* a blank line)? 208 * (Description:)? (Description of function)? 209 * (section header: (section description)? )* 210 (*)?*/ 211 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). 219 220 Use the section header "Return" for sections describing the return value 221 of a function. 222 223 Avoid putting a spurious blank line after the function name, or else the 224 description will be repeated! 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 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 238 Return: 239 0 - cool 240 1 - invalid arg 241 2 - out of memory 242 243 this will all run together and produce: 244 245 Return: 0 - cool 1 - invalid arg 2 - out of memory 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 252 Return: 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 260 Take a look around the source tree for examples. 261 262 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 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. 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; 291 /* private: internal use only */ 292 int c; 293 }; 294 295 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 319 DOC: sections are used in ReST files. 320 321 Tim. 322 */ <twaugh@redhat.com>
