Documentation/kernel-doc-nano-HOWTO.txt

   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>