linux/Documentation/kernel-doc-nano-HOWTO.txt
<<
>>
Prefs
   1NOTE: this document is outdated and will eventually be removed.  See
   2Documentation/kernel-documentation.rst 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, some
  21SGML templates in Documentation/DocBook, 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, 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
 158How to extract the documentation
 159--------------------------------
 160
 161If you just want to read the ready-made books on the various
 162subsystems (see Documentation/DocBook/*.tmpl), just type 'make
 163psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
 164preference.  If you would rather read a different format, you can type
 165'make xmldocs' and then use DocBook tools to convert
 166Documentation/DocBook/*.xml to a format of your choice (for example,
 167'db2html ...' if 'make htmldocs' was not defined).
 168
 169If 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
 175Here is split-man.pl:
 176
 177-->
 178#!/usr/bin/perl
 179
 180if ($#ARGV < 0) {
 181   die "where do I put the results?\n";
 182}
 183
 184mkdir $ARGV[0],0777;
 185$state = 0;
 186while (<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
 199close OUT;
 200<--
 201
 202If you just want to view the documentation for one function in one
 203file, you can do this:
 204
 205$ scripts/kernel-doc -man -function fn file | nroff -man | less
 206
 207or this:
 208
 209$ scripts/kernel-doc -text -function fn file
 210
 211
 212How to add extractable documentation to your source files
 213---------------------------------------------------------
 214
 215The 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
 225All "description" text can span multiple lines, although the
 226function_name & its short description are traditionally on a single line.
 227Description text may also contain blank lines (i.e., lines that contain
 228only a "*").
 229
 230"section header:" names must be unique per function (or struct,
 231union, typedef, enum).
 232
 233Use the section header "Return" for sections describing the return value
 234of a function.
 235
 236Avoid putting a spurious blank line after the function name, or else the
 237description will be repeated!
 238
 239All descriptive text is further processed, scanning for the following special
 240patterns, 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
 248NOTE 1:  The multi-line descriptive text you provide does *not* recognize
 249line 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
 256this will all run together and produce:
 257
 258  Return: 0 - cool 1 - invalid arg 2 - out of memory
 259
 260NOTE 2:  If the descriptive text you provide has lines that begin with
 261some phrase followed by a colon, each of those phrases will be taken as
 262a new section heading, which means you should similarly try to avoid text
 263like:
 264
 265  Return:
 266    0: cool
 267    1: invalid arg
 268    2: out of memory
 269
 270every line of which would start a new section.  Again, probably not
 271what you were after.
 272
 273Take a look around the source tree for examples.
 274
 275
 276kernel-doc for structs, unions, enums, and typedefs
 277---------------------------------------------------
 278
 279Beside functions you can also write documentation for structs, unions,
 280enums and typedefs. Instead of the function name you must write the name
 281of the declaration;  the struct/union/enum/typedef must always precede
 282the name. Nesting of declarations is not supported.
 283Use the argument mechanism to document members or constants.
 284
 285Inside a struct description, you can use the "private:" and "public:"
 286comment tags.  Structure fields that are inside a "private:" area
 287are not listed in the generated output documentation.  The "private:"
 288and "public:" tags must begin immediately following a "/*" comment
 289marker.  They may optionally include comments between the ":" and the
 290ending "*/" marker.
 291
 292Example:
 293
 294/**
 295 * struct my_struct - short description
 296 * @a: first member
 297 * @b: second member
 298 *
 299 * Longer description
 300 */
 301struct my_struct {
 302    int a;
 303    int b;
 304/* private: internal use only */
 305    int c;
 306};
 307
 308
 309Including documentation blocks in source files
 310----------------------------------------------
 311
 312To facilitate having source code and comments close together, you can
 313include kernel-doc documentation blocks that are free-form comments
 314instead of being kernel-doc for functions, structures, unions,
 315enums, or typedefs.  This could be used for something like a
 316theory of operation for a driver or library code, for example.
 317
 318This 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
 332DOC: sections are used in SGML templates files as indicated below.
 333
 334
 335How to make new SGML template files
 336-----------------------------------
 337
 338SGML template files (*.tmpl) are like normal SGML files, except that
 339they can contain escape sequences where extracted documentation should
 340be inserted.
 341
 342!E<filename> is replaced by the documentation, in <filename>, for
 343functions that are exported using EXPORT_SYMBOL: the function list is
 344collected 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
 350exported using EXPORT_SYMBOL.
 351
 352!F<filename> <function [functions...]> is replaced by the
 353documentation, in <filename>, for the functions listed.
 354
 355!P<filename> <section title> is replaced by the contents of the DOC:
 356section titled <section title> from <filename>.
 357Spaces 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
 360all DOC: sections and documented functions, symbols, etc. are used.
 361This makes sense to use when you use !F/!P only and want to verify
 362that all documentation is included.
 363
 364Tim.
 365*/ <twaugh@redhat.com>
 366