ia64/linux-2.6.18-xen.hg

annotate Documentation/kernel-doc-nano-HOWTO.txt @ 854:950b9eb27661

usbback: fix urb interval value for interrupt urbs.

Signed-off-by: Noboru Iwamatsu <n_iwamatsu@jp.fujitsu.com>
author Keir Fraser <keir.fraser@citrix.com>
date Mon Apr 06 13:51:20 2009 +0100 (2009-04-06)
parents 831230e53067
children
rev   line source
ian@0 1 kernel-doc nano-HOWTO
ian@0 2 =====================
ian@0 3
ian@0 4 Many places in the source tree have extractable documentation in the
ian@0 5 form of block comments above functions. The components of this system
ian@0 6 are:
ian@0 7
ian@0 8 - scripts/kernel-doc
ian@0 9
ian@0 10 This is a perl script that hunts for the block comments and can mark
ian@0 11 them up directly into DocBook, man, text, and HTML. (No, not
ian@0 12 texinfo.)
ian@0 13
ian@0 14 - Documentation/DocBook/*.tmpl
ian@0 15
ian@0 16 These are SGML template files, which are normal SGML files with
ian@0 17 special place-holders for where the extracted documentation should
ian@0 18 go.
ian@0 19
ian@0 20 - scripts/docproc.c
ian@0 21
ian@0 22 This is a program for converting SGML template files into SGML
ian@0 23 files. When a file is referenced it is searched for symbols
ian@0 24 exported (EXPORT_SYMBOL), to be able to distinguish between internal
ian@0 25 and external functions.
ian@0 26 It invokes kernel-doc, giving it the list of functions that
ian@0 27 are to be documented.
ian@0 28 Additionally it is used to scan the SGML template files to locate
ian@0 29 all the files referenced herein. This is used to generate dependency
ian@0 30 information as used by make.
ian@0 31
ian@0 32 - Makefile
ian@0 33
ian@0 34 The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
ian@0 35 to build DocBook files, PostScript files, PDF files, and html files
ian@0 36 in Documentation/DocBook.
ian@0 37
ian@0 38 - Documentation/DocBook/Makefile
ian@0 39
ian@0 40 This is where C files are associated with SGML templates.
ian@0 41
ian@0 42
ian@0 43 How to extract the documentation
ian@0 44 --------------------------------
ian@0 45
ian@0 46 If you just want to read the ready-made books on the various
ian@0 47 subsystems (see Documentation/DocBook/*.tmpl), just type 'make
ian@0 48 psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
ian@0 49 preference. If you would rather read a different format, you can type
ian@0 50 'make sgmldocs' and then use DocBook tools to convert
ian@0 51 Documentation/DocBook/*.sgml to a format of your choice (for example,
ian@0 52 'db2html ...' if 'make htmldocs' was not defined).
ian@0 53
ian@0 54 If you want to see man pages instead, you can do this:
ian@0 55
ian@0 56 $ cd linux
ian@0 57 $ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
ian@0 58 $ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man
ian@0 59
ian@0 60 Here is split-man.pl:
ian@0 61
ian@0 62 -->
ian@0 63 #!/usr/bin/perl
ian@0 64
ian@0 65 if ($#ARGV < 0) {
ian@0 66 die "where do I put the results?\n";
ian@0 67 }
ian@0 68
ian@0 69 mkdir $ARGV[0],0777;
ian@0 70 $state = 0;
ian@0 71 while (<STDIN>) {
ian@0 72 if (/^\.TH \"[^\"]*\" 4 \"([^\"]*)\"/) {
ian@0 73 if ($state == 1) { close OUT }
ian@0 74 $state = 1;
ian@0 75 $fn = "$ARGV[0]/$1.4";
ian@0 76 print STDERR "Creating $fn\n";
ian@0 77 open OUT, ">$fn" or die "can't open $fn: $!\n";
ian@0 78 print OUT $_;
ian@0 79 } elsif ($state != 0) {
ian@0 80 print OUT $_;
ian@0 81 }
ian@0 82 }
ian@0 83
ian@0 84 close OUT;
ian@0 85 <--
ian@0 86
ian@0 87 If you just want to view the documentation for one function in one
ian@0 88 file, you can do this:
ian@0 89
ian@0 90 $ scripts/kernel-doc -man -function fn file | nroff -man | less
ian@0 91
ian@0 92 or this:
ian@0 93
ian@0 94 $ scripts/kernel-doc -text -function fn file
ian@0 95
ian@0 96
ian@0 97 How to add extractable documentation to your source files
ian@0 98 ---------------------------------------------------------
ian@0 99
ian@0 100 The format of the block comment is like this:
ian@0 101
ian@0 102 /**
ian@0 103 * function_name(:)? (- short description)?
ian@0 104 (* @parameterx: (description of parameter x)?)*
ian@0 105 (* a blank line)?
ian@0 106 * (Description:)? (Description of function)?
ian@0 107 * (section header: (section description)? )*
ian@0 108 (*)?*/
ian@0 109
ian@0 110 The short function description cannot be multiline, but the other
ian@0 111 descriptions can be (and they can contain blank lines). Avoid putting a
ian@0 112 spurious blank line after the function name, or else the description will
ian@0 113 be repeated!
ian@0 114
ian@0 115 All descriptive text is further processed, scanning for the following special
ian@0 116 patterns, which are highlighted appropriately.
ian@0 117
ian@0 118 'funcname()' - function
ian@0 119 '$ENVVAR' - environment variable
ian@0 120 '&struct_name' - name of a structure (up to two words including 'struct')
ian@0 121 '@parameter' - name of a parameter
ian@0 122 '%CONST' - name of a constant.
ian@0 123
ian@0 124 Take a look around the source tree for examples.
ian@0 125
ian@0 126
ian@0 127 kernel-doc for structs, unions, enums, and typedefs
ian@0 128 ---------------------------------------------------
ian@0 129
ian@0 130 Beside functions you can also write documentation for structs, unions,
ian@0 131 enums and typedefs. Instead of the function name you must write the name
ian@0 132 of the declaration; the struct/union/enum/typedef must always precede
ian@0 133 the name. Nesting of declarations is not supported.
ian@0 134 Use the argument mechanism to document members or constants.
ian@0 135
ian@0 136 Inside a struct description, you can use the "private:" and "public:"
ian@0 137 comment tags. Structure fields that are inside a "private:" area
ian@0 138 are not listed in the generated output documentation.
ian@0 139
ian@0 140 Example:
ian@0 141
ian@0 142 /**
ian@0 143 * struct my_struct - short description
ian@0 144 * @a: first member
ian@0 145 * @b: second member
ian@0 146 *
ian@0 147 * Longer description
ian@0 148 */
ian@0 149 struct my_struct {
ian@0 150 int a;
ian@0 151 int b;
ian@0 152 /* private: */
ian@0 153 int c;
ian@0 154 };
ian@0 155
ian@0 156
ian@0 157 How to make new SGML template files
ian@0 158 -----------------------------------
ian@0 159
ian@0 160 SGML template files (*.tmpl) are like normal SGML files, except that
ian@0 161 they can contain escape sequences where extracted documentation should
ian@0 162 be inserted.
ian@0 163
ian@0 164 !E<filename> is replaced by the documentation, in <filename>, for
ian@0 165 functions that are exported using EXPORT_SYMBOL: the function list is
ian@0 166 collected from files listed in Documentation/DocBook/Makefile.
ian@0 167
ian@0 168 !I<filename> is replaced by the documentation for functions that are
ian@0 169 _not_ exported using EXPORT_SYMBOL.
ian@0 170
ian@0 171 !D<filename> is used to name additional files to search for functions
ian@0 172 exported using EXPORT_SYMBOL.
ian@0 173
ian@0 174 !F<filename> <function [functions...]> is replaced by the
ian@0 175 documentation, in <filename>, for the functions listed.
ian@0 176
ian@0 177
ian@0 178 Tim.
ian@0 179 */ <twaugh@redhat.com>