Linus,
Please put this in Documentation/kernel-doc-nano-HOWTO.txt.
Thanks,
Tim.
*/
kernel-doc nano-HOWTO
=====================
Many places in the source tree have extractable documentation in the
form of block comments above functions. The components of this system
are:
- scripts/kernel-doc
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
texinfo.)
- Documentation/DocBook/*.tmpl
These are SGML template files, which are normal SGML files with
special place-holders for where the extracted documentation should
go.
- scripts/docproc.c
This is a program for converting SGML template files into SGML
files. It invokes kernel-doc, giving it the list of functions that
are to be documented.
- scripts/gen-all-syms
This is a script that lists the EXPORT_SYMBOL symbols in a list of C
files.
- scripts/docgen
This script invokes docproc, telling it which functions are to be
documented (this list comes from gen-all-syms).
- Makefile
The targets 'sgmldocs', 'psdocs', and 'pdfdocs' are used to build
DocBook files, PostScript files, and PDF files in
Documentation/DocBook.
- Documentation/DocBook/Makefile
This is where C files are associated with SGML templates.
How to extract the documentation
--------------------------------
If you just want to read the ready-made books on the various
subsystems (see Documentation/DocBook/*.tmpl), just type 'make
psdocs', or 'make pdfdocs', depending on your preference. If you
would rather read a different format, you can type 'make sgmldocs' and
then use DocBook tools to convert Documentation/DocBook/*.sgml to a
format of your choice (for example, 'db2html ...').
If you want to see man pages instead, you can do this:
$ cd linux
$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
Here is split-man.pl:
-->
#!/usr/bin/perl
if ($#ARGV < 0) {
die "where do I put the results?\n";
}
mkdir $ARGV[0],0777 or die "Can't create $ARGV[0]: $!\n";
$state = 0;
while (<STDIN>) {
if (/^\.TH \"[^\"]*\" 4 \"([^\"]*)\"/) {
if ($state == 1) { close OUT }
$state = 1;
$fn = "$ARGV[0]/$1.4";
print STDERR "Creating $fn\n";
open OUT, ">$fn" or die "can't open $fn: $!\n";
print OUT $_;
} elsif ($state != 0) {
print OUT $_;
}
}
close OUT;
<--
If you just want to view the documentation for one function in one
file, you can do this:
$ scripts/kernel-doc -man -function fn file | nroff -man | less
or this:
$ scripts/kernel-doc -text -function fn file
How to add extractable documentation to your source files
---------------------------------------------------------
The format of the block comment is like this:
/**
* function_name(:)? (- short description)?
(* @parameterx: (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.
All descriptive text is further processed, scanning for the following special
patterns, which are highlighted appropriately.
'funcname()' - function
'$ENVVAR' - environment variable
'&struct_name' - name of a structure (up to two words including 'struct')
'@parameter' - name of a parameter
'%CONST' - name of a constant.
Take a look around the source tree for examples.
Tim.
*/ <twaugh@redhat.com>
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Fri May 19 2000 - 06:00:43 EDT