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