Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
[PATCH] Doc/kernel-doc: add more usage info
- Add info that structs, unions, enums, and typedefs are supported.
- Add doc about "private:" and "public:" tags for struct fields.
- Fix some typos.
- Remove some trailing whitespace.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
authored by
Randy Dunlap
and committed by
Linus Torvalds
d28bee0c
7045f37b
+37
-8
+34
-5
Documentation/kernel-doc-nano-HOWTO.txt
+34
-5
Documentation/kernel-doc-nano-HOWTO.txt
···
45
45
46
46
If you just want to read the ready-made books on the various
47
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,
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
52
'db2html ...' if 'make htmldocs' was not defined).
53
53
54
54
If you want to see man pages instead, you can do this:
···
124
124
Take a look around the source tree for examples.
125
125
126
126
127
+
kernel-doc for structs, unions, enums, and typedefs
128
+
---------------------------------------------------
129
+
130
+
Beside functions you can also write documentation for structs, unions,
131
+
enums and typedefs. Instead of the function name you must write the name
132
+
of the declaration; the struct/union/enum/typedef must always precede
133
+
the name. Nesting of declarations is not supported.
134
+
Use the argument mechanism to document members or constants.
135
+
136
+
Inside a struct description, you can use the "private:" and "public:"
137
+
comment tags. Structure fields that are inside a "private:" area
138
+
are not listed in the generated output documentation.
139
+
140
+
Example:
141
+
142
+
/**
143
+
* struct my_struct - short description
144
+
* @a: first member
145
+
* @b: second member
146
+
*
147
+
* Longer description
148
+
*/
149
+
struct my_struct {
150
+
int a;
151
+
int b;
152
+
/* private: */
153
+
int c;
154
+
};
155
+
156
+
127
157
How to make new SGML template files
128
158
-----------------------------------
129
159
···
177
147
178
148
Tim.
179
149
*/ <twaugh@redhat.com>
180
-
+3
-3
scripts/kernel-doc
+3
-3
scripts/kernel-doc
···
45
45
# Note: This only supports 'c'.
46
46
47
47
# usage:
48
-
# kerneldoc [ -docbook | -html | -text | -man ]
48
+
# kernel-doc [ -docbook | -html | -text | -man ]
49
49
# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
50
50
# or
51
51
# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
···
59
59
# -nofunction funcname
60
60
# If set, then only generate documentation for the other function(s). All
61
61
# other functions are ignored. Cannot be used with -function together
62
-
# (yes thats a bug - perl hackers can fix it 8))
62
+
# (yes, that's a bug -- perl hackers can fix it 8))
63
63
#
64
64
# c files - list of 'c' files to process
65
65
#
···
434
434
print "<hr>\n";
435
435
}
436
436
437
-
# output tyepdef in html
437
+
# output typedef in html
438
438
sub output_typedef_html(%) {
439
439
my %args = %{$_[0]};
440
440
my ($parameter);