kernel-doc nano-HOWTO
=====================
+How to format kernel-doc comments
+---------------------------------
+
+In order to provide embedded, 'C' friendly, easy to maintain,
+but consistent and extractable documentation of the functions and
+data structures in the Linux kernel, the Linux kernel has adopted
+a consistent style for documenting functions and their parameters,
+and structures and their members.
+
+The format for this documentation is called the kernel-doc format.
+It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
+
+This style embeds the documentation within the source files, using
+a few simple conventions. The scripts/kernel-doc perl script, some
+SGML templates in Documentation/DocBook, and other tools understand
+these conventions, and are used to extract this embedded documentation
+into various documents.
+
+In order to provide good documentation of kernel functions and data
+structures, please use the following conventions to format your
+kernel-doc comments in Linux kernel source.
+
+We definitely need kernel-doc formatted documentation for functions
+that are exported to loadable modules using EXPORT_SYMBOL.
+
+We also look to provide kernel-doc formatted documentation for
+functions externally visible to other kernel files (not marked
+"static").
+
+We also recommend providing kernel-doc formatted documentation
+for private (file "static") routines, for consistency of kernel
+source code layout. But this is lower priority and at the
+discretion of the MAINTAINER of that kernel source file.
+
+Data structures visible in kernel include files should also be
+documented using kernel-doc formatted comments.
+
+The opening comment mark "/**" is reserved for kernel-doc comments.
+Only comments so marked will be considered by the kernel-doc scripts,
+and any comment so marked must be in kernel-doc format. Do not use
+"/**" to be begin a comment block unless the comment block contains
+kernel-doc formatted comments. The closing comment marker for
+kernel-doc comments can be either "*/" or "**/".
+
+Kernel-doc comments should be placed just before the function
+or data structure being described.
+
+Example kernel-doc function comment:
+
+/**
+ * foobar() - short function description of foobar
+ * @arg1: Describe the first argument to foobar.
+ * @arg2: Describe the second argument to foobar.
+ * One can provide multiple line descriptions
+ * for arguments.
+ *
+ * A longer description, with more discussion of the function foobar()
+ * that might be useful to those using or modifying it. Begins with
+ * empty comment line, and may include additional embedded empty
+ * comment lines.
+ *
+ * The longer description can have multiple paragraphs.
+ **/
+
+The first line, with the short description, must be on a single line.
+
+The @argument descriptions must begin on the very next line following
+this opening short function description line, with no intervening
+empty comment lines.
+
+Example kernel-doc data structure comment.
+
+/**
+ * struct blah - the basic blah structure
+ * @mem1: describe the first member of struct blah
+ * @mem2: describe the second member of struct blah,
+ * perhaps with more lines and words.
+ *
+ * Longer description of this structure.
+ **/
+
+The kernel-doc function comments describe each parameter to the
+function, in order, with the @name lines.
+
+The kernel-doc data structure comments describe each structure member
+in the data structure, with the @name lines.
+
+The longer description formatting is "reflowed", losing your line
+breaks. So presenting carefully formatted lists within these
+descriptions won't work so well; derived documentation will lose
+the formatting.
+
+See the section below "How to add extractable documentation to your
+source files" for more details and notes on how to format kernel-doc
+comments.
+
+Components of the kernel-doc system
+-----------------------------------
+
Many places in the source tree have extractable documentation in the
form of block comments above functions. The components of this system
are:
special place-holders for where the extracted documentation should
go.
-- scripts/docproc.c
+- scripts/basic/docproc.c
This is a program for converting SGML template files into SGML
files. When a file is referenced it is searched for symbols
mkdir $ARGV[0],0777;
$state = 0;
while (<STDIN>) {
- if (/^\.TH \"[^\"]*\" 4 \"([^\"]*)\"/) {
+ if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
if ($state == 1) { close OUT }
$state = 1;
- $fn = "$ARGV[0]/$1.4";
+ $fn = "$ARGV[0]/$1.9";
print STDERR "Creating $fn\n";
open OUT, ">$fn" or die "can't open $fn: $!\n";
print OUT $_;
/**
* function_name(:)? (- short description)?
-(* @parameterx: (description of parameter x)?)*
+(* @parameterx(space)*: (description of parameter x)?)*
(* a blank line)?
* (Description:)? (Description of function)?
* (section header: (section description)? )*
(*)?*/
-The short function description cannot be multiline, but the other
-descriptions can be (and they can contain blank lines). Avoid putting a
-spurious blank line after the function name, or else the description will
-be repeated!
+The short function description ***cannot be multiline***, but the other
+descriptions can be (and they can contain blank lines). If you continue
+that initial short description onto a second line, that second line will
+appear further down at the beginning of the description section, which is
+almost certainly not what you had in mind.
+
+Avoid putting a spurious blank line after the function name, or else the
+description will be repeated!
All descriptive text is further processed, scanning for the following special
patterns, which are highlighted appropriately.
'@parameter' - name of a parameter
'%CONST' - name of a constant.
+NOTE 1: The multi-line descriptive text you provide does *not* recognize
+line breaks, so if you try to format some text nicely, as in:
+
+ Return codes
+ 0 - cool
+ 1 - invalid arg
+ 2 - out of memory
+
+this will all run together and produce:
+
+ Return codes 0 - cool 1 - invalid arg 2 - out of memory
+
+NOTE 2: If the descriptive text you provide has lines that begin with
+some phrase followed by a colon, each of those phrases will be taken as
+a new section heading, which means you should similarly try to avoid text
+like:
+
+ Return codes:
+ 0: cool
+ 1: invalid arg
+ 2: out of memory
+
+every line of which would start a new section. Again, probably not
+what you were after.
+
Take a look around the source tree for examples.