diff options
author | Randy Dunlap <randy.dunlap@oracle.com> | 2008-04-28 02:16:34 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2008-04-28 08:58:48 -0700 |
commit | 94dc7ad5502e7d74e2fd74651743f5f1773aa1fe (patch) | |
tree | bc3c58105501b9fcba90b3e686a44c9d8e9ef8b3 /scripts/kernel-doc | |
parent | 9f354858b8ea29e969b82dd96caea376157d76ca (diff) | |
download | kernel_samsung_smdk4412-94dc7ad5502e7d74e2fd74651743f5f1773aa1fe.tar.gz kernel_samsung_smdk4412-94dc7ad5502e7d74e2fd74651743f5f1773aa1fe.tar.bz2 kernel_samsung_smdk4412-94dc7ad5502e7d74e2fd74651743f5f1773aa1fe.zip |
kernel-doc: detect/prevent duplicate doc section names
I saw this problem recently. With this kernel-doc:
* Note: some important info
*
* Note: other important info
kernel-doc uses the "section name" (preceding the ':', like "Note") as a hash
key for storing the descriptive text ("blah important info"). It is (was)
possible to have duplicate (colliding) section names, without any kind of
warning or error.
kernel-doc happily used the latter descriptive text for all instances of
printing the <section-name> descriptive text and the former important info
was lost.
One way to "fix" this is to modify the kernel-doc comments, e.g.:
* Note1: foo bar
*
* Note.2: blah zay
For now, kernel-doc will signal an error when it sees colliding section names
like this.
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-x | scripts/kernel-doc | 20 |
1 files changed, 13 insertions, 7 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 263d04ab2d9..99364a5e77f 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 <twaugh@redhat.com> ## ## Copyright (C) 2001 Simon Huggins ## -## Copyright (C) 2005-2007 Randy Dunlap ## +## Copyright (C) 2005-2008 Randy Dunlap ## ## ## ## #define enhancements by Armin Kuster <akuster@mvista.com> ## ## Copyright (c) 2000 MontaVista Software, Inc. ## @@ -366,6 +366,7 @@ foreach my $pattern (keys %highlights) { # dumps section contents to arrays/hashes intended for that purpose. # sub dump_section { + my $file = shift; my $name = shift; my $contents = join "\n", @_; @@ -379,6 +380,10 @@ sub dump_section { $parameterdescs{$name} = $contents; } else { # print STDERR "other section '$name' = '$contents'\n"; + if (defined($sections{$name}) && ($sections{$name} ne "")) { + print STDERR "Error(${file}:$.): duplicate section name '$name'\n"; + ++$errors; + } $sections{$name} = $contents; push @sectionlist, $name; } @@ -388,6 +393,7 @@ sub dump_section { # dump DOC: section after checking that it should go out # sub dump_doc_section { + my $file = shift; my $name = shift; my $contents = join "\n", @_; @@ -399,7 +405,7 @@ sub dump_doc_section { ( $function_only == 1 && defined($function_table{$name})) || ( $function_only == 2 && !defined($function_table{$name}))) { - dump_section $name, $contents; + dump_section($file, $name, $contents); output_blockhead({'sectionlist' => \@sectionlist, 'sections' => \%sections, 'module' => $modulename, @@ -1923,7 +1929,7 @@ sub process_file($) { print STDERR "Warning(${file}:$.): contents before sections\n"; ++$warnings; } - dump_section($section, xml_escape($contents)); + dump_section($file, $section, xml_escape($contents)); $section = $section_default; } @@ -1940,7 +1946,7 @@ sub process_file($) { } elsif (/$doc_end/) { if ($contents ne "") { - dump_section($section, xml_escape($contents)); + dump_section($file, $section, xml_escape($contents)); $section = $section_default; $contents = ""; } @@ -1954,7 +1960,7 @@ sub process_file($) { # @parameter line to signify start of description if ($1 eq "" && ($section =~ m/^@/ || $section eq $section_context)) { - dump_section($section, xml_escape($contents)); + dump_section($file, $section, xml_escape($contents)); $section = $section_default; $contents = ""; } else { @@ -1974,7 +1980,7 @@ sub process_file($) { } elsif ($state == 4) { # Documentation block if (/$doc_block/) { - dump_doc_section($section, xml_escape($contents)); + dump_doc_section($file, $section, xml_escape($contents)); $contents = ""; $function = ""; %constants = (); @@ -1992,7 +1998,7 @@ sub process_file($) { } elsif (/$doc_end/) { - dump_doc_section($section, xml_escape($contents)); + dump_doc_section($file, $section, xml_escape($contents)); $contents = ""; $function = ""; %constants = (); |