Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 94dc7ad5 authored by Randy Dunlap's avatar Randy Dunlap Committed by Linus Torvalds
Browse files

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: default avatarRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 9f354858

scripts/kernel-doc

+13 −7
Original line number Original line Diff line number Diff line
@@ -5,7 +5,7 @@ use strict; 
## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##

## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##

## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##

## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##

## Copyright (C) 2001  Simon Huggins                             ##

## 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>	 ##

## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##

## Copyright (c) 2000 MontaVista Software, Inc.			 ##

## 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.

# dumps section contents to arrays/hashes intended for that purpose.

#

#

sub dump_section {

sub dump_section {

    my $file = shift;

    my $name = shift;

    my $name = shift;

    my $contents = join "\n", @_;

    my $contents = join "\n", @_;
@@ -379,6 +380,10 @@ sub dump_section { 
	$parameterdescs{$name} = $contents;

	$parameterdescs{$name} = $contents;

    } else {

    } else {

#	print STDERR "other section '$name' = '$contents'\n";

#	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;

	$sections{$name} = $contents;

	push @sectionlist, $name;

	push @sectionlist, $name;

    }

    }
@@ -388,6 +393,7 @@ sub dump_section { 
# dump DOC: section after checking that it should go out

# dump DOC: section after checking that it should go out

#

#

sub dump_doc_section {

sub dump_doc_section {

    my $file = shift;

    my $name = shift;

    my $name = shift;

    my $contents = join "\n", @_;

    my $contents = join "\n", @_;
@@ -399,7 +405,7 @@ sub dump_doc_section { 
	( $function_only == 1 && defined($function_table{$name})) ||

	( $function_only == 1 && defined($function_table{$name})) ||

	( $function_only == 2 && !defined($function_table{$name})))

	( $function_only == 2 && !defined($function_table{$name})))

    {

    {

	dump_section $name, $contents;

	dump_section($file, $name, $contents);

	output_blockhead({'sectionlist' => \@sectionlist,

	output_blockhead({'sectionlist' => \@sectionlist,

			  'sections' => \%sections,

			  'sections' => \%sections,

			  'module' => $modulename,

			  'module' => $modulename,
@@ -1923,7 +1929,7 @@ sub process_file($) { 
			print STDERR "Warning(${file}:$.): contents before sections\n";

			print STDERR "Warning(${file}:$.): contents before sections\n";

			++$warnings;

			++$warnings;

		    }

		    }

		    dump_section($section, xml_escape($contents));

		    dump_section($file, $section, xml_escape($contents));

		    $section = $section_default;

		    $section = $section_default;

		}

		}
@@ -1940,7 +1946,7 @@ sub process_file($) { 
	    } elsif (/$doc_end/) {

	    } elsif (/$doc_end/) {





		if ($contents ne "") {

		if ($contents ne "") {

		    dump_section($section, xml_escape($contents));

		    dump_section($file, $section, xml_escape($contents));

		    $section = $section_default;

		    $section = $section_default;

		    $contents = "";

		    $contents = "";

		}

		}
@@ -1954,7 +1960,7 @@ sub process_file($) { 
		# @parameter line to signify start of description

		# @parameter line to signify start of description

		if ($1 eq "" &&

		if ($1 eq "" &&

			($section =~ m/^@/ || $section eq $section_context)) {

			($section =~ m/^@/ || $section eq $section_context)) {

		    dump_section($section, xml_escape($contents));

		    dump_section($file, $section, xml_escape($contents));

		    $section = $section_default;

		    $section = $section_default;

		    $contents = "";

		    $contents = "";

		} else {

		} else {
@@ -1974,7 +1980,7 @@ sub process_file($) { 
	} elsif ($state == 4) {

	} elsif ($state == 4) {

		# Documentation block

		# Documentation block

		if (/$doc_block/) {

		if (/$doc_block/) {

			dump_doc_section($section, xml_escape($contents));

			dump_doc_section($file, $section, xml_escape($contents));

			$contents = "";

			$contents = "";

			$function = "";

			$function = "";

			%constants = ();

			%constants = ();
@@ -1992,7 +1998,7 @@ sub process_file($) { 
		}

		}

		elsif (/$doc_end/)

		elsif (/$doc_end/)

		{

		{

			dump_doc_section($section, xml_escape($contents));

			dump_doc_section($file, $section, xml_escape($contents));

			$contents = "";

			$contents = "";

			$function = "";

			$function = "";

			%constants = ();

			%constants = ();