Subversion Repositories or1k

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', 'pdfdocs', and 'htmldocs' are used

  to build DocBook files, PostScript files, PDF files, and html 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', or 'make htmldocs', 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 'make htmldocs' was not defined).

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

$ scripts/kernel-doc -man $(find -name '*.h') | 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;

$state = 0;

while () {

    if (/^\.TH \"[^\"]*\" (\d) \"([^\"]*)\"/) {

        if ($state == 1) { close OUT }

        $state = 1;

        $fn = "$ARGV[0]/$2.$1";

        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 (and they can contain blank lines). 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.

'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.

How to make new SGML template files

-----------------------------------

SGML template files (*.tmpl) are like normal SGML files, except that

they can contain escape sequences where extracted documentation should

be inserted.

!E is replaced by the documentation, in , for

functions that are exported using EXPORT_SYMBOL: the function list is

collected from files listed in Documentation/DocBook/Makefile.

!I is replaced by the documentation for functions that are

_not_ exported using EXPORT_SYMBOL.

!F  is replaced by the

documentation, in , for the functions listed.

Tim.

*/