From d28bee0c0a9c6abddf1d14c69f188400e994eb5a Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 1 Feb 2006 03:06:57 -0800 Subject: [PATCH] [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 Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/kernel-doc-nano-HOWTO.txt | 39 +++++++++++++++++++++---- 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 , for the functions listed. Tim. */ - 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 "
\n"; } -# output tyepdef in html +# output typedef in html sub output_typedef_html(%) { my %args = %{$_[0]}; my ($parameter);