aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRandy Dunlap <randy.dunlap@oracle.com>2008-04-28 05:16:34 -0400
committerLinus Torvalds <torvalds@linux-foundation.org>2008-04-28 11:58:48 -0400
commit94dc7ad5502e7d74e2fd74651743f5f1773aa1fe (patch)
treebc3c58105501b9fcba90b3e686a44c9d8e9ef8b3
parent9f354858b8ea29e969b82dd96caea376157d76ca (diff)
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>
-rwxr-xr-xscripts/kernel-doc20
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;
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## 5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ## 6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ## 7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2007 Randy Dunlap ## 8## Copyright (C) 2005-2008 Randy Dunlap ##
9## ## 9## ##
10## #define enhancements by Armin Kuster <akuster@mvista.com> ## 10## #define enhancements by Armin Kuster <akuster@mvista.com> ##
11## Copyright (c) 2000 MontaVista Software, Inc. ## 11## Copyright (c) 2000 MontaVista Software, Inc. ##
@@ -366,6 +366,7 @@ foreach my $pattern (keys %highlights) {
366# dumps section contents to arrays/hashes intended for that purpose. 366# dumps section contents to arrays/hashes intended for that purpose.
367# 367#
368sub dump_section { 368sub dump_section {
369 my $file = shift;
369 my $name = shift; 370 my $name = shift;
370 my $contents = join "\n", @_; 371 my $contents = join "\n", @_;
371 372
@@ -379,6 +380,10 @@ sub dump_section {
379 $parameterdescs{$name} = $contents; 380 $parameterdescs{$name} = $contents;
380 } else { 381 } else {
381# print STDERR "other section '$name' = '$contents'\n"; 382# print STDERR "other section '$name' = '$contents'\n";
383 if (defined($sections{$name}) && ($sections{$name} ne "")) {
384 print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
385 ++$errors;
386 }
382 $sections{$name} = $contents; 387 $sections{$name} = $contents;
383 push @sectionlist, $name; 388 push @sectionlist, $name;
384 } 389 }
@@ -388,6 +393,7 @@ sub dump_section {
388# dump DOC: section after checking that it should go out 393# dump DOC: section after checking that it should go out
389# 394#
390sub dump_doc_section { 395sub dump_doc_section {
396 my $file = shift;
391 my $name = shift; 397 my $name = shift;
392 my $contents = join "\n", @_; 398 my $contents = join "\n", @_;
393 399
@@ -399,7 +405,7 @@ sub dump_doc_section {
399 ( $function_only == 1 && defined($function_table{$name})) || 405 ( $function_only == 1 && defined($function_table{$name})) ||
400 ( $function_only == 2 && !defined($function_table{$name}))) 406 ( $function_only == 2 && !defined($function_table{$name})))
401 { 407 {
402 dump_section $name, $contents; 408 dump_section($file, $name, $contents);
403 output_blockhead({'sectionlist' => \@sectionlist, 409 output_blockhead({'sectionlist' => \@sectionlist,
404 'sections' => \%sections, 410 'sections' => \%sections,
405 'module' => $modulename, 411 'module' => $modulename,
@@ -1923,7 +1929,7 @@ sub process_file($) {
1923 print STDERR "Warning(${file}:$.): contents before sections\n"; 1929 print STDERR "Warning(${file}:$.): contents before sections\n";
1924 ++$warnings; 1930 ++$warnings;
1925 } 1931 }
1926 dump_section($section, xml_escape($contents)); 1932 dump_section($file, $section, xml_escape($contents));
1927 $section = $section_default; 1933 $section = $section_default;
1928 } 1934 }
1929 1935
@@ -1940,7 +1946,7 @@ sub process_file($) {
1940 } elsif (/$doc_end/) { 1946 } elsif (/$doc_end/) {
1941 1947
1942 if ($contents ne "") { 1948 if ($contents ne "") {
1943 dump_section($section, xml_escape($contents)); 1949 dump_section($file, $section, xml_escape($contents));
1944 $section = $section_default; 1950 $section = $section_default;
1945 $contents = ""; 1951 $contents = "";
1946 } 1952 }
@@ -1954,7 +1960,7 @@ sub process_file($) {
1954 # @parameter line to signify start of description 1960 # @parameter line to signify start of description
1955 if ($1 eq "" && 1961 if ($1 eq "" &&
1956 ($section =~ m/^@/ || $section eq $section_context)) { 1962 ($section =~ m/^@/ || $section eq $section_context)) {
1957 dump_section($section, xml_escape($contents)); 1963 dump_section($file, $section, xml_escape($contents));
1958 $section = $section_default; 1964 $section = $section_default;
1959 $contents = ""; 1965 $contents = "";
1960 } else { 1966 } else {
@@ -1974,7 +1980,7 @@ sub process_file($) {
1974 } elsif ($state == 4) { 1980 } elsif ($state == 4) {
1975 # Documentation block 1981 # Documentation block
1976 if (/$doc_block/) { 1982 if (/$doc_block/) {
1977 dump_doc_section($section, xml_escape($contents)); 1983 dump_doc_section($file, $section, xml_escape($contents));
1978 $contents = ""; 1984 $contents = "";
1979 $function = ""; 1985 $function = "";
1980 %constants = (); 1986 %constants = ();
@@ -1992,7 +1998,7 @@ sub process_file($) {
1992 } 1998 }
1993 elsif (/$doc_end/) 1999 elsif (/$doc_end/)
1994 { 2000 {
1995 dump_doc_section($section, xml_escape($contents)); 2001 dump_doc_section($file, $section, xml_escape($contents));
1996 $contents = ""; 2002 $contents = "";
1997 $function = ""; 2003 $function = "";
1998 %constants = (); 2004 %constants = ();