From d960eea974f5e500c0dcb95a934239cc1f481cfd Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Mon, 29 Jun 2009 14:54:11 -0700 Subject: kernel-doc: move ignoring kmemcheck Somehow I managed to generate a diff that put these 2 lines into the wrong function: should have been in dump_struct() instead of in dump_enum(). Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ed591e9b7d1d..b52d340d759d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1426,6 +1426,8 @@ sub dump_struct($$) { # strip comments: $members =~ s/\/\*.*?\*\///gos; $nested =~ s/\/\*.*?\*\///gos; + # strip kmemcheck_bitfield_{begin,end}.*; + $members =~ s/kmemcheck_bitfield_.*?;//gos; create_parameterlist($members, ';', $file); check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); @@ -1468,8 +1470,6 @@ sub dump_enum($$) { } } - # strip kmemcheck_bitfield_{begin,end}.*; - $members =~ s/kmemcheck_bitfield_.*?;//gos; output_declaration($declaration_name, 'enum', -- cgit v1.2.3 From 6423133bdee0e07d1c2f8411cb3fe676c207ba33 Mon Sep 17 00:00:00 2001 From: Johannes Weiner Date: Thu, 17 Sep 2009 19:26:53 -0700 Subject: kernel-doc: allow multi-line declaration purpose descriptions Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this: /** * unmap_mapping_range - unmap the portion of all mmaps in the * specified address_space corresponding to the specified * page range in the underlying file. * @mapping: the address space containing mmaps to be unmapped. * ... */ The short description ends with a parameter description, an empty line or the end of the comment block. Signed-off-by: Johannes Weiner Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b52d340d759d..ea9f8a58678f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1995,6 +1995,7 @@ sub process_file($) { my $identifier; my $func; my $descr; + my $in_purpose = 0; my $initial_section_counter = $section_counter; if (defined($ENV{'SRCTREE'})) { @@ -2044,6 +2045,7 @@ sub process_file($) { $descr =~ s/\s*$//; $descr =~ s/\s+/ /; $declaration_purpose = xml_escape($descr); + $in_purpose = 1; } else { $declaration_purpose = ""; } @@ -2090,6 +2092,7 @@ sub process_file($) { } $in_doc_sect = 1; + $in_purpose = 0; $contents = $newcontents; if ($contents ne "") { while ((substr($contents, 0, 1) eq " ") || @@ -2119,11 +2122,19 @@ sub process_file($) { } elsif (/$doc_content/) { # miguel-style comment kludge, look for blank lines after # @parameter line to signify start of description - if ($1 eq "" && - ($section =~ m/^@/ || $section eq $section_context)) { - dump_section($file, $section, xml_escape($contents)); - $section = $section_default; - $contents = ""; + if ($1 eq "") { + if ($section =~ m/^@/ || $section eq $section_context) { + dump_section($file, $section, xml_escape($contents)); + $section = $section_default; + $contents = ""; + } else { + $contents .= "\n"; + } + $in_purpose = 0; + } elsif ($in_purpose == 1) { + # Continued declaration purpose + chomp($declaration_purpose); + $declaration_purpose .= " " . xml_escape($1); } else { $contents .= $1 . "\n"; } -- cgit v1.2.3 From 3a9089fd78367e2c6c815129030b790a0f5c2715 Mon Sep 17 00:00:00 2001 From: Jason Baron Date: Tue, 1 Dec 2009 12:18:49 -0500 Subject: tracing: Add DEFINE_EVENT(), DEFINE_SINGLE_EVENT() support to docbook The introduction of the new 'DECLARE_EVENT_CLASS()' obviates the need for the 'TRACE_EVENT()' macro in some cases. Thus, docbook style comments that used to live with 'TRACE_EVENT()' are now moved to 'DEFINE_EVENT()'. Thus, we need to make the docbook system understand the new 'DEFINE_EVENT()' macro. In addition I've tried to futureproof the patch, by also adding support for 'DEFINE_SINGLE_EVENT()', since there has been discussion about renaming: TRACE_EVENT() -> DEFINE_SINGLE_EVENT(). Without this patch the tracepoint docbook fails to build. I've verified that this patch correctly builds the tracepoint docbook which currently covers signals, and irqs. Changes in v2: - properly indent perl 'if' statements Signed-off-by: Jason Baron Acked-by: Steven Rostedt Acked-by: Randy Dunlap Cc: William Cohen Cc: Frederic Weisbecker Cc: Mathieu Desnoyers Cc: Masami Hiramatsu LKML-Reference: <200912011718.nB1HIn7t011371@int-mx04.intmail.prod.int.phx2.redhat.com> Signed-off-by: Ingo Molnar --- scripts/kernel-doc | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ea9f8a58678f..241310e59cd6 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1852,10 +1852,17 @@ sub tracepoint_munge($) { my $tracepointname = 0; my $tracepointargs = 0; - if($prototype =~ m/TRACE_EVENT\((.*?),/) { + if ($prototype =~ m/TRACE_EVENT\((.*?),/) { $tracepointname = $1; } - if($prototype =~ m/TP_PROTO\((.*?)\)/) { + if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) { + $tracepointname = $1; + } + if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) { + $tracepointname = $2; + } + $tracepointname =~ s/^\s+//; #strip leading whitespace + if ($prototype =~ m/TP_PROTO\((.*?)\)/) { $tracepointargs = $1; } if (($tracepointname eq 0) || ($tracepointargs eq 0)) { @@ -1920,7 +1927,9 @@ sub process_state3_function($$) { if ($prototype =~ /SYSCALL_DEFINE/) { syscall_munge(); } - if ($prototype =~ /TRACE_EVENT/) { + if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ || + $prototype =~ /DEFINE_SINGLE_EVENT/) + { tracepoint_munge($file); } dump_function($prototype, $file); -- cgit v1.2.3 From a9e7314b7940cee00b80995b360dbc06f995cc6e Mon Sep 17 00:00:00 2001 From: Ilya Dryomov Date: Fri, 26 Feb 2010 13:05:47 -0800 Subject: kernel-doc: track line numbers for each file separately The problem is that $. keeps track of the current record number (which is line number by default). But if you pass it multiple files, it does not wrap at the end of file, and therefore contains the *total* number of processed lines. I suppose we can fix line numbering by introducing a simple assignment $. = 1 before processing every new file. Signed-off-by: Ilya Dryomov Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 241310e59cd6..8018f6a1dd04 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2023,6 +2023,8 @@ sub process_file($) { return; } + $. = 1; + $section_counter = 0; while () { if ($state == 0) { -- cgit v1.2.3 From 1c32fd0c5ac1ccbdc37a1a392a5d75cbe059b401 Mon Sep 17 00:00:00 2001 From: Ilya Dryomov Date: Fri, 26 Feb 2010 13:06:03 -0800 Subject: kernel-doc: drop the -filelist option, it doesn't work I also found the -filelist option, but apparently the implementation is broken, and it was broken from the very first git commit. For the -filelist option I suggest the removal (I wasn't able to find any users of it, moreover it's not even listed in the usage() output, so presumably nobody knows about it). Signed-off-by: Ilya Dryomov Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8018f6a1dd04..208ad3b0ca51 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -13,8 +13,6 @@ use strict; ## This software falls under the GNU General Public License. ## ## Please read the COPYING file for more information ## -# w.o. 03-11-2000: added the '-filelist' option. - # 18/01/2001 - Cleanups # Functions prototyped as foo(void) same as foo() # Stop eval'ing where we don't need to. @@ -245,7 +243,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', # could cause "use of undefined value" or other bugs. my ($function, %function_table, %parametertypes, $declaration_purpose); my ($type, $declaration_name, $return_type); -my ($newsection, $newcontents, $prototype, $filelist, $brcount, %source_map); +my ($newsection, $newcontents, $prototype, $brcount, %source_map); if (defined($ENV{'KBUILD_VERBOSE'})) { $verbose = "$ENV{'KBUILD_VERBOSE'}"; @@ -338,8 +336,6 @@ while ($ARGV[0] =~ m/^-(.*)/) { $verbose = 1; } elsif (($cmd eq "-h") || ($cmd eq "--help")) { usage(); - } elsif ($cmd eq '-filelist') { - $filelist = shift @ARGV; } elsif ($cmd eq '-no-doc-sections') { $no_doc_sections = 1; } @@ -1811,14 +1807,6 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { close(SOURCE_MAP); } -if ($filelist) { - open(FLIST,"<$filelist") or die "Can't open file list $filelist"; - while() { - chop; - process_file($_); - } -} - foreach (@ARGV) { chomp; process_file($_); -- cgit v1.2.3 From 4c98ecaf350737cd424eb94140e9e9f1a3408956 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 10 Mar 2010 15:22:02 -0800 Subject: scripts/kernel-doc: fix empty function description section scripts/kernel-doc mishandles a function that has a multi-line function short description and no function parameters. The observed problem was from drivers/scsi/scsi_netlink.c: /** * scsi_netlink_init - Called by SCSI subsystem to intialize * the SCSI transport netlink interface * **/ kernel-doc treated the " * " line as a Description: section with only a newline character in the Description contents. This caused output_highlight() to complain: "output_highlight got called with no args?", plus produce a perl call stack backtrace. The fix is just to ignore Description sections if they only contain "\n". Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 208ad3b0ca51..c7865c362d28 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2103,7 +2103,7 @@ sub process_file($) { $section = $newsection; } elsif (/$doc_end/) { - if ($contents ne "") { + if (($contents ne "") && ($contents ne "\n")) { dump_section($file, $section, xml_escape($contents)); $section = $section_default; $contents = ""; -- cgit v1.2.3 From ef5da59f12602815baa8fad98241b77dedea3b31 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 23 Mar 2010 13:35:14 -0700 Subject: scripts/kernel-doc: handle struct member __aligned scripts/kernel-doc erroneously says: Warning(include/linux/skbuff.h:410): Excess struct/union/enum/typedef member 'cb' description in 'sk_buff' on this line in struct sk_buff: char cb[48] __aligned(8); due to treating the last field as the struct member name, so teach kernel-doc to ignore __aligned(x) in structs. Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c7865c362d28..c297eb4785d6 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1424,6 +1424,8 @@ sub dump_struct($$) { $nested =~ s/\/\*.*?\*\///gos; # strip kmemcheck_bitfield_{begin,end}.*; $members =~ s/kmemcheck_bitfield_.*?;//gos; + # strip attributes + $members =~ s/__aligned\s*\(\d+\)//gos; create_parameterlist($members, ';', $file); check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); -- cgit v1.2.3 From 20072205fcdf7d85cd3101f1f11dfab333c5fd0c Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 23 Mar 2010 13:35:24 -0700 Subject: scripts/kernel-doc: fix fatal error on function prototype Fix a fatal error in scripts/kernel-doc when a function signature uses __init_or_module (just ignore that string): Error(drivers/base/platform.c:568): cannot understand prototype: 'struct platform_device * __init_or_module platform_create_bundle(struct platform_driver *driver, int (*probe)(struct platform_device *), struct resource *res, unsigned int n_res, const void *data, size_t size) ' Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c297eb4785d6..fcdfb245a575 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1730,6 +1730,7 @@ sub dump_function($$) { $prototype =~ s/^noinline +//; $prototype =~ s/__devinit +//; $prototype =~ s/__init +//; + $prototype =~ s/__init_or_module +//; $prototype =~ s/^#\s*define\s+//; #ak added $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//; -- cgit v1.2.3 From b6d676db35ca6c99180bb12dcbd4a8c3b2995e49 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 10 Aug 2010 18:02:50 -0700 Subject: mtd/nand_base: fix kernel-doc warnings & typos Fix mtd/nand_base.c kernel-doc warnings and typos. Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len' Signed-off-by: Randy Dunlap Cc: David Woodhouse Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index fcdfb245a575..102e1235fd5c 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1454,6 +1454,8 @@ sub dump_enum($$) { my $file = shift; $x =~ s@/\*.*?\*/@@gos; # strip comments. + $x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums + if ($x =~ /enum\s+(\w+)\s*{(.*)}/) { $declaration_name = $1; my $members = $2; -- cgit v1.2.3 From 1f3a66889c4c80c821f3eadf899c140e91452f8e Mon Sep 17 00:00:00 2001 From: Johannes Berg Date: Sat, 11 Sep 2010 15:55:12 -0700 Subject: kernel-doc: ignore case when stripping attributes There are valid attributes that could have upper case letters, but we still want to remove, like for example __attribute__((aligned(NETDEV_ALIGN))) as encountered in the wireless code. Signed-off-by: Johannes Berg Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 102e1235fd5c..a68240c188f3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1679,7 +1679,7 @@ sub check_sections($$$$$$) { foreach $px (0 .. $#prms) { $prm_clean = $prms[$px]; $prm_clean =~ s/\[.*\]//; - $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//; + $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i; # ignore array size in a parameter string; # however, the original param string may contain # spaces, e.g.: addr[6 + 2] -- cgit v1.2.3 From eda603f6cdba4b14dbf80531fab2fe545232e7a0 Mon Sep 17 00:00:00 2001 From: Johannes Berg Date: Sat, 11 Sep 2010 15:55:22 -0700 Subject: docbook: warn on unused doc entries When you don't use !E or !I but only !F, then it's very easy to miss including some functions, structs etc. in documentation. To help finding which ones were missed, allow printing out the unused ones as warnings. For example, using this on mac80211 yields a lot of warnings like this: Warning: didn't use docs for DOC: mac80211 workqueue Warning: didn't use docs for ieee80211_max_queues Warning: didn't use docs for ieee80211_bss_change Warning: didn't use docs for ieee80211_bss_conf when generating the documentation for it. Signed-off-by: Johannes Berg Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a68240c188f3..cdb6dc1f6458 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -44,12 +44,13 @@ use strict; # Note: This only supports 'c'. # usage: -# kernel-doc [ -docbook | -html | -text | -man ] [ -no-doc-sections ] +# kernel-doc [ -docbook | -html | -text | -man | -list ] [ -no-doc-sections ] # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile # or # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile # # Set output format using one of -docbook -html -text or -man. Default is man. +# The -list format is for internal use by docproc. # # -no-doc-sections # Do not output DOC: sections @@ -210,9 +211,16 @@ my %highlights_text = ( $type_constant, "\$1", $type_param, "\$1" ); my $blankline_text = ""; +# list mode +my %highlights_list = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +my $blankline_list = ""; sub usage { - print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n"; + print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n"; + print " [ -no-doc-sections ]\n"; print " [ -function funcname [ -function funcname ...] ]\n"; print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; print " c source file(s) > outputfile\n"; @@ -318,6 +326,10 @@ while ($ARGV[0] =~ m/^-(.*)/) { $output_mode = "xml"; %highlights = %highlights_xml; $blankline = $blankline_xml; + } elsif ($cmd eq "-list") { + $output_mode = "list"; + %highlights = %highlights_list; + $blankline = $blankline_list; } elsif ($cmd eq "-gnome") { $output_mode = "gnome"; %highlights = %highlights_gnome; @@ -1361,6 +1373,42 @@ sub output_blockhead_text(%) { } } +## list mode output functions + +sub output_function_list(%) { + my %args = %{$_[0]}; + + print $args{'function'} . "\n"; +} + +# output enum in list +sub output_enum_list(%) { + my %args = %{$_[0]}; + print $args{'enum'} . "\n"; +} + +# output typedef in list +sub output_typedef_list(%) { + my %args = %{$_[0]}; + print $args{'typedef'} . "\n"; +} + +# output struct as list +sub output_struct_list(%) { + my %args = %{$_[0]}; + + print $args{'struct'} . "\n"; +} + +sub output_blockhead_list(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + foreach $section (@{$args{'sectionlist'}}) { + print "DOC: $section\n"; + } +} + ## # generic output function for all types (function, struct/union, typedef, enum); # calls the generated, variable output_ function name based on -- cgit v1.2.3 From 2b35f4d9cab365d37c7b34ce51e1c1144c312d05 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 18 Nov 2010 12:27:31 -0800 Subject: kernel-doc: escape xml for structs scripts/kernel-doc was leaving unescaped '<', '>', and '&' in generated xml output for structs. This causes xml parser errors. Convert these characters to "<", ">", and "&" as needed to prevent errors. Most of the conversion was already done; complete it just before output. Documentation/DocBook/device-drivers.xml:41883: parser error : StartTag: invalid element name #define INPUT_KEYMAP_BY_INDEX (1 << 0) Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cdb6dc1f6458..39580a5dc5df 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -5,7 +5,7 @@ use strict; ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## ## Copyright (C) 2000, 1 Tim Waugh ## ## Copyright (C) 2001 Simon Huggins ## -## Copyright (C) 2005-2009 Randy Dunlap ## +## Copyright (C) 2005-2010 Randy Dunlap ## ## ## ## #define enhancements by Armin Kuster ## ## Copyright (c) 2000 MontaVista Software, Inc. ## @@ -453,7 +453,7 @@ sub output_highlight { if ($output_mode eq "html" || $output_mode eq "xml") { $contents = local_unescape($contents); # convert data read & converted thru xml_escape() into &xyz; format: - $contents =~ s/\\\\\\/&/g; + $contents =~ s/\\\\\\/\&/g; } # print STDERR "contents b4:$contents\n"; eval $dohighlight; @@ -770,7 +770,11 @@ sub output_struct_xml(%) { print $args{'type'} . " " . $args{'struct'} . " {\n"; foreach $parameter (@{$args{'parameterlist'}}) { if ($parameter =~ /^#/) { - print "$parameter\n"; + my $prm = $parameter; + # convert data read & converted thru xml_escape() into &xyz; format: + # This allows us to have #define macros interspersed in a struct. + $prm =~ s/\\\\\\/\&/g; + print "$prm\n"; next; } @@ -1701,6 +1705,8 @@ sub push_parameter($$$) { } } + $param = xml_escape($param); + # strip spaces from $param so that it is one continous string # on @parameterlist; # this fixes a problem where check_sections() cannot find -- cgit v1.2.3 From 8484baaa5065b460e5eb18ee721d8417251f7897 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 5 Jan 2011 16:28:43 -0800 Subject: kernel-doc: code reorganization Move 'main' code vs. subroutines around so that they are not so intermixed, for better readability/understanding (relative to Perl). It was messy to follow the primary flow of code execution with the code being mixed. Now the code begins with data initialization, followed by all subroutines, then ends with the main code execution. This is almost totally source code movement, with a few changes as needed for forward declarations. Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 102 ++++++++++++++++++++++++++++------------------------- 1 file changed, 54 insertions(+), 48 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 39580a5dc5df..9f85012acf0d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -155,6 +155,8 @@ use strict; # '@parameter' - name of a parameter # '%CONST' - name of a constant. +## init lots of data + my $errors = 0; my $warnings = 0; my $anon_struct_union = 0; @@ -218,21 +220,14 @@ my %highlights_list = ( $type_constant, "\$1", $type_param, "\$1" ); my $blankline_list = ""; -sub usage { - print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n"; - print " [ -no-doc-sections ]\n"; - print " [ -function funcname [ -function funcname ...] ]\n"; - print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; - print " c source file(s) > outputfile\n"; - print " -v : verbose output, more warnings & other info listed\n"; - exit 1; -} - # read arguments if ($#ARGV == -1) { usage(); } +my $kernelversion; +my $dohighlight = ""; + my $verbose = 0; my $output_mode = "man"; my $no_doc_sections = 0; @@ -245,7 +240,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 'November', 'December')[(localtime)[4]] . " " . ((localtime)[5]+1900); -# Essentially these are globals +# Essentially these are globals. # They probably want to be tidied up, made more localised or something. # CAVEAT EMPTOR! Some of the others I localised may not want to be, which # could cause "use of undefined value" or other bugs. @@ -353,6 +348,18 @@ while ($ARGV[0] =~ m/^-(.*)/) { } } +# continue execution near EOF; + +sub usage { + print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n"; + print " [ -no-doc-sections ]\n"; + print " [ -function funcname [ -function funcname ...] ]\n"; + print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; + print " c source file(s) > outputfile\n"; + print " -v : verbose output, more warnings & other info listed\n"; + exit 1; +} + # get kernel version from env sub get_kernel_version() { my $version = 'unknown kernel version'; @@ -362,15 +369,6 @@ sub get_kernel_version() { } return $version; } -my $kernelversion = get_kernel_version(); - -# generate a sequence of code that will splice in highlighting information -# using the s// operator. -my $dohighlight = ""; -foreach my $pattern (keys %highlights) { -# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; - $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; -} ## # dumps section contents to arrays/hashes intended for that purpose. @@ -1851,34 +1849,6 @@ sub dump_function($$) { }); } -sub process_file($); - -# Read the file that maps relative names to absolute names for -# separate source and object directories and for shadow trees. -if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { - my ($relname, $absname); - while() { - chop(); - ($relname, $absname) = (split())[0..1]; - $relname =~ s:^/+::; - $source_map{$relname} = $absname; - } - close(SOURCE_MAP); -} - -foreach (@ARGV) { - chomp; - process_file($_); -} -if ($verbose && $errors) { - print STDERR "$errors errors\n"; -} -if ($verbose && $warnings) { - print STDERR "$warnings warnings\n"; -} - -exit($errors); - sub reset_state { $function = ""; %constants = (); @@ -2285,3 +2255,39 @@ sub process_file($) { } } } + + +$kernelversion = get_kernel_version(); + +# generate a sequence of code that will splice in highlighting information +# using the s// operator. +foreach my $pattern (keys %highlights) { +# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; + $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; +} + +# Read the file that maps relative names to absolute names for +# separate source and object directories and for shadow trees. +if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { + my ($relname, $absname); + while() { + chop(); + ($relname, $absname) = (split())[0..1]; + $relname =~ s:^/+::; + $source_map{$relname} = $absname; + } + close(SOURCE_MAP); +} + +foreach (@ARGV) { + chomp; + process_file($_); +} +if ($verbose && $errors) { + print STDERR "$errors errors\n"; +} +if ($verbose && $warnings) { + print STDERR "$warnings warnings\n"; +} + +exit($errors); -- cgit v1.2.3