kernel-doc nano-HOWTO
|
kernel-doc nano-HOWTO
|
=====================
|
=====================
|
|
|
Many places in the source tree have extractable documentation in the
|
Many places in the source tree have extractable documentation in the
|
form of block comments above functions. The components of this system
|
form of block comments above functions. The components of this system
|
are:
|
are:
|
|
|
- scripts/kernel-doc
|
- scripts/kernel-doc
|
|
|
This is a perl script that hunts for the block comments and can mark
|
This is a perl script that hunts for the block comments and can mark
|
them up directly into DocBook, man, text, and HTML. (No, not
|
them up directly into DocBook, man, text, and HTML. (No, not
|
texinfo.)
|
texinfo.)
|
|
|
- Documentation/DocBook/*.tmpl
|
- Documentation/DocBook/*.tmpl
|
|
|
These are SGML template files, which are normal SGML files with
|
These are SGML template files, which are normal SGML files with
|
special place-holders for where the extracted documentation should
|
special place-holders for where the extracted documentation should
|
go.
|
go.
|
|
|
- scripts/docproc.c
|
- scripts/docproc.c
|
|
|
This is a program for converting SGML template files into SGML
|
This is a program for converting SGML template files into SGML
|
files. It invokes kernel-doc, giving it the list of functions that
|
files. It invokes kernel-doc, giving it the list of functions that
|
are to be documented.
|
are to be documented.
|
|
|
- scripts/gen-all-syms
|
- scripts/gen-all-syms
|
|
|
This is a script that lists the EXPORT_SYMBOL symbols in a list of C
|
This is a script that lists the EXPORT_SYMBOL symbols in a list of C
|
files.
|
files.
|
|
|
- scripts/docgen
|
- scripts/docgen
|
|
|
This script invokes docproc, telling it which functions are to be
|
This script invokes docproc, telling it which functions are to be
|
documented (this list comes from gen-all-syms).
|
documented (this list comes from gen-all-syms).
|
|
|
- Makefile
|
- Makefile
|
|
|
The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
|
The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
|
to build DocBook files, PostScript files, PDF files, and html files
|
to build DocBook files, PostScript files, PDF files, and html files
|
in Documentation/DocBook.
|
in Documentation/DocBook.
|
|
|
- Documentation/DocBook/Makefile
|
- Documentation/DocBook/Makefile
|
|
|
This is where C files are associated with SGML templates.
|
This is where C files are associated with SGML templates.
|
|
|
|
|
How to extract the documentation
|
How to extract the documentation
|
--------------------------------
|
--------------------------------
|
|
|
If you just want to read the ready-made books on the various
|
If you just want to read the ready-made books on the various
|
subsystems (see Documentation/DocBook/*.tmpl), just type 'make
|
subsystems (see Documentation/DocBook/*.tmpl), just type 'make
|
psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
|
psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
|
preference. If you would rather read a different format, you can type
|
preference. If you would rather read a different format, you can type
|
'make sgmldocs' and then use DocBook tools to convert
|
'make sgmldocs' and then use DocBook tools to convert
|
Documentation/DocBook/*.sgml to a format of your choice (for example,
|
Documentation/DocBook/*.sgml to a format of your choice (for example,
|
'db2html ...' if 'make htmldocs' was not defined).
|
'db2html ...' if 'make htmldocs' was not defined).
|
|
|
If you want to see man pages instead, you can do this:
|
If you want to see man pages instead, you can do this:
|
|
|
$ cd linux
|
$ cd linux
|
$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
|
$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
|
$ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man
|
$ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man
|
|
|
Here is split-man.pl:
|
Here is split-man.pl:
|
|
|
-->
|
-->
|
#!/usr/bin/perl
|
#!/usr/bin/perl
|
|
|
if ($#ARGV < 0) {
|
if ($#ARGV < 0) {
|
die "where do I put the results?\n";
|
die "where do I put the results?\n";
|
}
|
}
|
|
|
mkdir $ARGV[0],0777;
|
mkdir $ARGV[0],0777;
|
$state = 0;
|
$state = 0;
|
while () {
|
while () {
|
if (/^\.TH \"[^\"]*\" (\d) \"([^\"]*)\"/) {
|
if (/^\.TH \"[^\"]*\" (\d) \"([^\"]*)\"/) {
|
if ($state == 1) { close OUT }
|
if ($state == 1) { close OUT }
|
$state = 1;
|
$state = 1;
|
$fn = "$ARGV[0]/$2.$1";
|
$fn = "$ARGV[0]/$2.$1";
|
print STDERR "Creating $fn\n";
|
print STDERR "Creating $fn\n";
|
open OUT, ">$fn" or die "can't open $fn: $!\n";
|
open OUT, ">$fn" or die "can't open $fn: $!\n";
|
print OUT $_;
|
print OUT $_;
|
} elsif ($state != 0) {
|
} elsif ($state != 0) {
|
print OUT $_;
|
print OUT $_;
|
}
|
}
|
}
|
}
|
|
|
close OUT;
|
close OUT;
|
<--
|
<--
|
|
|
If you just want to view the documentation for one function in one
|
If you just want to view the documentation for one function in one
|
file, you can do this:
|
file, you can do this:
|
|
|
$ scripts/kernel-doc -man -function fn file | nroff -man | less
|
$ scripts/kernel-doc -man -function fn file | nroff -man | less
|
|
|
or this:
|
or this:
|
|
|
$ scripts/kernel-doc -text -function fn file
|
$ scripts/kernel-doc -text -function fn file
|
|
|
|
|
How to add extractable documentation to your source files
|
How to add extractable documentation to your source files
|
---------------------------------------------------------
|
---------------------------------------------------------
|
|
|
The format of the block comment is like this:
|
The format of the block comment is like this:
|
|
|
/**
|
/**
|
* function_name(:)? (- short description)?
|
* function_name(:)? (- short description)?
|
(* @parameterx: (description of parameter x)?)*
|
(* @parameterx: (description of parameter x)?)*
|
(* a blank line)?
|
(* a blank line)?
|
* (Description:)? (Description of function)?
|
* (Description:)? (Description of function)?
|
* (section header: (section description)? )*
|
* (section header: (section description)? )*
|
(*)?*/
|
(*)?*/
|
|
|
The short function description cannot be multiline, but the other
|
The short function description cannot be multiline, but the other
|
descriptions can be (and they can contain blank lines). Avoid putting a
|
descriptions can be (and they can contain blank lines). Avoid putting a
|
spurious blank line after the function name, or else the description will
|
spurious blank line after the function name, or else the description will
|
be repeated!
|
be repeated!
|
|
|
All descriptive text is further processed, scanning for the following special
|
All descriptive text is further processed, scanning for the following special
|
patterns, which are highlighted appropriately.
|
patterns, which are highlighted appropriately.
|
|
|
'funcname()' - function
|
'funcname()' - function
|
'$ENVVAR' - environment variable
|
'$ENVVAR' - environment variable
|
'&struct_name' - name of a structure (up to two words including 'struct')
|
'&struct_name' - name of a structure (up to two words including 'struct')
|
'@parameter' - name of a parameter
|
'@parameter' - name of a parameter
|
'%CONST' - name of a constant.
|
'%CONST' - name of a constant.
|
|
|
Take a look around the source tree for examples.
|
Take a look around the source tree for examples.
|
|
|
|
|
How to make new SGML template files
|
How to make new SGML template files
|
-----------------------------------
|
-----------------------------------
|
|
|
SGML template files (*.tmpl) are like normal SGML files, except that
|
SGML template files (*.tmpl) are like normal SGML files, except that
|
they can contain escape sequences where extracted documentation should
|
they can contain escape sequences where extracted documentation should
|
be inserted.
|
be inserted.
|
|
|
!E is replaced by the documentation, in , for
|
!E is replaced by the documentation, in , for
|
functions that are exported using EXPORT_SYMBOL: the function list is
|
functions that are exported using EXPORT_SYMBOL: the function list is
|
collected from files listed in Documentation/DocBook/Makefile.
|
collected from files listed in Documentation/DocBook/Makefile.
|
|
|
!I is replaced by the documentation for functions that are
|
!I is replaced by the documentation for functions that are
|
_not_ exported using EXPORT_SYMBOL.
|
_not_ exported using EXPORT_SYMBOL.
|
|
|
!F is replaced by the
|
!F is replaced by the
|
documentation, in , for the functions listed.
|
documentation, in , for the functions listed.
|
|
|
|
|
Tim.
|
Tim.
|
*/
|
*/
|
|
|
|
|
