patch-2.3.99-pre9 linux/Documentation/kernel-doc-nano-HOWTO.txt

• Lines: 129
• Date: Sun May 21 20:18:07 2000
• Orig file: v2.3.99-pre8/linux/Documentation/kernel-doc-nano-HOWTO.txt
• Orig date: Wed Dec 31 16:00:00 1969

diff -u --recursive --new-file v2.3.99-pre8/linux/Documentation/kernel-doc-nano-HOWTO.txt linux/Documentation/kernel-doc-nano-HOWTO.txt
@@ -0,0 +1,128 @@
+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>
+