Commit d28bee0c authored by Randy Dunlap's avatar Randy Dunlap Committed by Linus Torvalds

[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: default avatarRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: default avatarAndrew Morton <akpm@osdl.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@osdl.org>
parent 7045f37b
...@@ -45,10 +45,10 @@ How to extract the documentation ...@@ -45,10 +45,10 @@ How to extract the documentation
If you just want to read the ready-made books on the various If you just want to read the ready-made books on the various
subsystems (see Documentation/DocBook/*.tmpl), just type 'make subsystems (see Documentation/DocBook/*.tmpl), just type 'make
psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
preference. If you would rather read a different format, you can type preference. If you would rather read a different format, you can type
'make sgmldocs' and then use DocBook tools to convert 'make sgmldocs' and then use DocBook tools to convert
Documentation/DocBook/*.sgml to a format of your choice (for example, Documentation/DocBook/*.sgml to a format of your choice (for example,
'db2html ...' if 'make htmldocs' was not defined). 'db2html ...' if 'make htmldocs' was not defined).
If you want to see man pages instead, you can do this: If you want to see man pages instead, you can do this:
...@@ -124,6 +124,36 @@ patterns, which are highlighted appropriately. ...@@ -124,6 +124,36 @@ patterns, which are highlighted appropriately.
Take a look around the source tree for examples. 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 How to make new SGML template files
----------------------------------- -----------------------------------
...@@ -147,4 +177,3 @@ documentation, in <filename>, for the functions listed. ...@@ -147,4 +177,3 @@ documentation, in <filename>, for the functions listed.
Tim. Tim.
*/ <twaugh@redhat.com> */ <twaugh@redhat.com>
...@@ -45,7 +45,7 @@ use strict; ...@@ -45,7 +45,7 @@ use strict;
# Note: This only supports 'c'. # Note: This only supports 'c'.
# usage: # usage:
# kerneldoc [ -docbook | -html | -text | -man ] # kernel-doc [ -docbook | -html | -text | -man ]
# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
# or # or
# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
...@@ -59,7 +59,7 @@ use strict; ...@@ -59,7 +59,7 @@ use strict;
# -nofunction funcname # -nofunction funcname
# If set, then only generate documentation for the other function(s). All # If set, then only generate documentation for the other function(s). All
# other functions are ignored. Cannot be used with -function together # 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 # c files - list of 'c' files to process
# #
...@@ -434,7 +434,7 @@ sub output_enum_html(%) { ...@@ -434,7 +434,7 @@ sub output_enum_html(%) {
print "<hr>\n"; print "<hr>\n";
} }
# output tyepdef in html # output typedef in html
sub output_typedef_html(%) { sub output_typedef_html(%) {
my %args = %{$_[0]}; my %args = %{$_[0]};
my ($parameter); my ($parameter);
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment