diff options
author | Randy Dunlap <rdunlap@xenotime.net> | 2006-02-01 14:06:57 +0300 |
---|---|---|
committer | Linus Torvalds <torvalds@g5.osdl.org> | 2006-02-01 19:53:27 +0300 |
commit | d28bee0c0a9c6abddf1d14c69f188400e994eb5a (patch) | |
tree | fb05862b35aa6f4f96867c9baeb4d6508d55bdb9 | |
parent | 7045f37b17ffa6e85435ca980122b46a74caa7e4 (diff) | |
download | linux-d28bee0c0a9c6abddf1d14c69f188400e994eb5a.tar.xz |
[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>
-rw-r--r-- | Documentation/kernel-doc-nano-HOWTO.txt | 39 | ||||
-rwxr-xr-x | scripts/kernel-doc | 6 |
2 files changed, 37 insertions, 8 deletions
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index c406ce67edd0..c65233d430f0 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -45,10 +45,10 @@ 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, +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: @@ -124,6 +124,36 @@ patterns, which are highlighted appropriately. Take a look around the source tree for examples. +kernel-doc for structs, unions, enums, and typedefs +--------------------------------------------------- + +Beside functions you can also write documentation for structs, unions, +enums and typedefs. Instead of the function name you must write the name +of the declaration; the struct/union/enum/typedef must always precede +the name. Nesting of declarations is not supported. +Use the argument mechanism to document members or constants. + +Inside a struct description, you can use the "private:" and "public:" +comment tags. Structure fields that are inside a "private:" area +are not listed in the generated output documentation. + +Example: + +/** + * struct my_struct - short description + * @a: first member + * @b: second member + * + * Longer description + */ +struct my_struct { + int a; + int b; +/* private: */ + int c; +}; + + How to make new SGML template files ----------------------------------- @@ -147,4 +177,3 @@ documentation, in <filename>, for the functions listed. Tim. */ <twaugh@redhat.com> - diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b927fd25e968..940fe348009f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -45,7 +45,7 @@ use strict; # Note: This only supports 'c'. # usage: -# kerneldoc [ -docbook | -html | -text | -man ] +# kernel-doc [ -docbook | -html | -text | -man ] # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile # or # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile @@ -59,7 +59,7 @@ use strict; # -nofunction funcname # If set, then only generate documentation for the other function(s). All # other functions are ignored. Cannot be used with -function together -# (yes thats a bug - perl hackers can fix it 8)) +# (yes, that's a bug -- perl hackers can fix it 8)) # # c files - list of 'c' files to process # @@ -434,7 +434,7 @@ sub output_enum_html(%) { print "<hr>\n"; } -# output tyepdef in html +# output typedef in html sub output_typedef_html(%) { my %args = %{$_[0]}; my ($parameter); |