1NOTE: this document is outdated and will eventually be removed. See 2Documentation/doc-guide/ for current information. 3 4kernel-doc nano-HOWTO 5===================== 6 7How to format kernel-doc comments 8--------------------------------- 9 10In order to provide embedded, 'C' friendly, easy to maintain, 11but consistent and extractable documentation of the functions and 12data structures in the Linux kernel, the Linux kernel has adopted 13a consistent style for documenting functions and their parameters, 14and structures and their members. 15 16The format for this documentation is called the kernel-doc format. 17It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file. 18 19This style embeds the documentation within the source files, using 20a few simple conventions. The scripts/kernel-doc perl script, the 21Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand 22these conventions, and are used to extract this embedded documentation 23into various documents. 24 25In order to provide good documentation of kernel functions and data 26structures, please use the following conventions to format your 27kernel-doc comments in Linux kernel source. 28 29We definitely need kernel-doc formatted documentation for functions 30that are exported to loadable modules using EXPORT_SYMBOL. 31 32We also look to provide kernel-doc formatted documentation for 33functions externally visible to other kernel files (not marked 34"static"). 35 36We also recommend providing kernel-doc formatted documentation 37for private (file "static") routines, for consistency of kernel 38source code layout. But this is lower priority and at the 39discretion of the MAINTAINER of that kernel source file. 40 41Data structures visible in kernel include files should also be 42documented using kernel-doc formatted comments. 43 44The opening comment mark "/**" is reserved for kernel-doc comments. 45Only comments so marked will be considered by the kernel-doc scripts, 46and 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 48kernel-doc formatted comments. The closing comment marker for 49kernel-doc comments can be either "*/" or "**/", but "*/" is 50preferred in the Linux kernel tree. 51 52Kernel-doc comments should be placed just before the function 53or data structure being described. 54 55Example 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 74The short description following the subject can span multiple lines 75and ends with an @argument description, an empty line or the end of 76the comment block. 77 78The @argument descriptions must begin on the very next line following 79this opening short function description line, with no intervening 80empty comment lines. 81 82If a function parameter is "..." (varargs), it should be listed in 83kernel-doc notation as: 84 * @...: description 85 86The return value, if any, should be described in a dedicated section 87named "Return". 88 89Example 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 100The kernel-doc function comments describe each parameter to the 101function, in order, with the @name lines. 102 103The kernel-doc data structure comments describe each structure member 104in the data structure, with the @name lines. 105 106The longer description formatting is "reflowed", losing your line 107breaks. So presenting carefully formatted lists within these 108descriptions won't work so well; derived documentation will lose 109the formatting. 110 111See the section below "How to add extractable documentation to your 112source files" for more details and notes on how to format kernel-doc 113comments. 114 115Components of the kernel-doc system 116----------------------------------- 117 118Many places in the source tree have extractable documentation in the 119form of block comments above functions. The components of this system 120are: 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 146How to extract the documentation 147-------------------------------- 148 149If you just want to read the ready-made books on the various 150subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs', 151depending on your preference. If you would rather read a different format, 152you can type 'make xmldocs' and then use DocBook tools to convert 153Documentation/output/*.xml to a format of your choice (for example, 154'db2html ...' if 'make htmldocs' was not defined). 155 156If 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 162Here is split-man.pl: 163 164--> 165#!/usr/bin/perl 166 167if ($#ARGV < 0) { 168 die "where do I put the results?\n"; 169} 170 171mkdir $ARGV[0],0777; 172$state = 0; 173while (<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 186close OUT; 187<-- 188 189If you just want to view the documentation for one function in one 190file, you can do this: 191 192$ scripts/kernel-doc -man -function fn file | nroff -man | less 193 194or this: 195 196$ scripts/kernel-doc -text -function fn file 197 198 199How to add extractable documentation to your source files 200--------------------------------------------------------- 201 202The 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 212All "description" text can span multiple lines, although the 213function_name & its short description are traditionally on a single line. 214Description text may also contain blank lines (i.e., lines that contain 215only a "*"). 216 217"section header:" names must be unique per function (or struct, 218union, typedef, enum). 219 220Use the section header "Return" for sections describing the return value 221of a function. 222 223Avoid putting a spurious blank line after the function name, or else the 224description will be repeated! 225 226All descriptive text is further processed, scanning for the following special 227patterns, 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 235NOTE 1: The multi-line descriptive text you provide does *not* recognize 236line 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 243this will all run together and produce: 244 245 Return: 0 - cool 1 - invalid arg 2 - out of memory 246 247NOTE 2: If the descriptive text you provide has lines that begin with 248some phrase followed by a colon, each of those phrases will be taken as 249a new section heading, which means you should similarly try to avoid text 250like: 251 252 Return: 253 0: cool 254 1: invalid arg 255 2: out of memory 256 257every line of which would start a new section. Again, probably not 258what you were after. 259 260Take a look around the source tree for examples. 261 262 263kernel-doc for structs, unions, enums, and typedefs 264--------------------------------------------------- 265 266Beside functions you can also write documentation for structs, unions, 267enums and typedefs. Instead of the function name you must write the name 268of the declaration; the struct/union/enum/typedef must always precede 269the name. Nesting of declarations is not supported. 270Use the argument mechanism to document members or constants. 271 272Inside a struct description, you can use the "private:" and "public:" 273comment tags. Structure fields that are inside a "private:" area 274are not listed in the generated output documentation. The "private:" 275and "public:" tags must begin immediately following a "/*" comment 276marker. They may optionally include comments between the ":" and the 277ending "*/" marker. 278 279Example: 280 281/** 282 * struct my_struct - short description 283 * @a: first member 284 * @b: second member 285 * 286 * Longer description 287 */ 288struct my_struct { 289 int a; 290 int b; 291/* private: internal use only */ 292 int c; 293}; 294 295 296Including documentation blocks in source files 297---------------------------------------------- 298 299To facilitate having source code and comments close together, you can 300include kernel-doc documentation blocks that are free-form comments 301instead of being kernel-doc for functions, structures, unions, 302enums, or typedefs. This could be used for something like a 303theory of operation for a driver or library code, for example. 304 305This 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 319DOC: sections are used in ReST files. 320 321Tim. 322*/ <twaugh@redhat.com> 323