microsoft
/
WSL2-Linux-Kernel
зеркало из https://github.com/microsoft/WSL2-Linux-Kernel.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

scripts/kernel-doc: Replacing highlights hash by an array 

The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted. It generates
faulty DocBook entries like:
	- @<function>device_for_each_child</function>

Sorting the result is not enough some times (as it's deterministic but
we can't control it).
We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight is correct.

[jc: I think this is kind of papering around the real problem, that people
 are saying @function() when "function" is not a parameter.  But this makes
 things better than they were before, so...]

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Danilo Cesar Lemes de Paula 2015-09-07 17:01:59 -03:00 коммит произвёл Jonathan Corbet
Родитель 17666497fe
Коммит 4d73270192
1 изменённых файлов: 60 добавлений и 44 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

104
scripts/kernel-doc
Просмотреть файл

@ -206,59 +206,73 @@ my $type_env = '(\$\w+)';
# One for each output format # One for each output format
# these work fairly well # these work fairly well
my %highlights_html = ( $type_constant, "<i>\$1</i>", my @highlights_html = (
$type_func, "<b>\$1</b>", [$type_constant, "<i>\$1</i>"],
$type_struct_xml, "<i>\$1</i>", [$type_func, "<b>\$1</b>"],
$type_env, "<b><i>\$1</i></b>", [$type_struct_xml, "<i>\$1</i>"],
$type_param, "<tt><b>\$1</b></tt>" ); [$type_env, "<b><i>\$1</i></b>"],
[$type_param, "<tt><b>\$1</b></tt>"]
);
my $local_lt = "\\\\\\\\lt:"; my $local_lt = "\\\\\\\\lt:";
my $local_gt = "\\\\\\\\gt:"; my $local_gt = "\\\\\\\\gt:";
my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>" my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
# html version 5 # html version 5
my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>", my @highlights_html5 = (
$type_func, "<span class=\"func\">\$1</span>", [$type_constant, "<span class=\"const\">\$1</span>"],
$type_struct_xml, "<span class=\"struct\">\$1</span>", [$type_func, "<span class=\"func\">\$1</span>"],
$type_env, "<span class=\"env\">\$1</span>", [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
$type_param, "<span class=\"param\">\$1</span>" ); [$type_env, "<span class=\"env\">\$1</span>"],
[$type_param, "<span class=\"param\">\$1</span>]"]
);
my $blankline_html5 = $local_lt . "br /" . $local_gt; my $blankline_html5 = $local_lt . "br /" . $local_gt;
# XML, docbook format # XML, docbook format
my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>", my @highlights_xml = (
$type_constant, "<constant>\$1</constant>", ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
$type_func, "<function>\$1</function>", [$type_constant, "<constant>\$1</constant>"],
$type_struct_xml, "<structname>\$1</structname>", [$type_struct_xml, "<structname>\$1</structname>"],
$type_env, "<envar>\$1</envar>", [$type_param, "<parameter>\$1</parameter>"],
$type_param, "<parameter>\$1</parameter>" ); [$type_func, "<function>\$1</function>"],
[$type_env, "<envar>\$1</envar>"]
);
my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
# gnome, docbook format # gnome, docbook format
my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>", my @highlights_gnome = (
$type_func, "<function>\$1</function>", [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
$type_struct, "<structname>\$1</structname>", [$type_func, "<function>\$1</function>"],
$type_env, "<envar>\$1</envar>", [$type_struct, "<structname>\$1</structname>"],
$type_param, "<parameter>\$1</parameter>" ); [$type_env, "<envar>\$1</envar>"],
[$type_param, "<parameter>\$1</parameter>" ]
);
my $blankline_gnome = "</para><para>\n"; my $blankline_gnome = "</para><para>\n";
# these are pretty rough # these are pretty rough
my %highlights_man = ( $type_constant, "\$1", my @highlights_man = (
$type_func, "\\\\fB\$1\\\\fP", [$type_constant, "\$1"],
$type_struct, "\\\\fI\$1\\\\fP", [$type_func, "\\\\fB\$1\\\\fP"],
$type_param, "\\\\fI\$1\\\\fP" ); [$type_struct, "\\\\fI\$1\\\\fP"],
[$type_param, "\\\\fI\$1\\\\fP"]
);
my $blankline_man = ""; my $blankline_man = "";
# text-mode # text-mode
my %highlights_text = ( $type_constant, "\$1", my @highlights_text = (
$type_func, "\$1", [$type_constant, "\$1"],
$type_struct, "\$1", [$type_func, "\$1"],
$type_param, "\$1" ); [$type_struct, "\$1"],
[$type_param, "\$1"]
);
my $blankline_text = ""; my $blankline_text = "";
# list mode # list mode
my %highlights_list = ( $type_constant, "\$1", my @highlights_list = (
$type_func, "\$1", [$type_constant, "\$1"],
$type_struct, "\$1", [$type_func, "\$1"],
$type_param, "\$1" ); [$type_struct, "\$1"],
[$type_param, "\$1"]
);
my $blankline_list = ""; my $blankline_list = "";
# read arguments # read arguments
@ -273,7 +287,7 @@ my $verbose = 0;
my $output_mode = "man"; my $output_mode = "man";
my $output_preformatted = 0; my $output_preformatted = 0;
my $no_doc_sections = 0; my $no_doc_sections = 0;
my %highlights = %highlights_man; my @highlights = @highlights_man;
my $blankline = $blankline_man; my $blankline = $blankline_man;
my $modulename = "Kernel API"; my $modulename = "Kernel API";
my $function_only = 0; my $function_only = 0;
@ -374,31 +388,31 @@ while ($ARGV[0] =~ m/^-(.*)/) {
my $cmd = shift @ARGV; my $cmd = shift @ARGV;
if ($cmd eq "-html") { if ($cmd eq "-html") {
$output_mode = "html"; $output_mode = "html";
%highlights = %highlights_html; @highlights = @highlights_html;
$blankline = $blankline_html; $blankline = $blankline_html;
} elsif ($cmd eq "-html5") { } elsif ($cmd eq "-html5") {
$output_mode = "html5"; $output_mode = "html5";
%highlights = %highlights_html5; @highlights = @highlights_html5;
$blankline = $blankline_html5; $blankline = $blankline_html5;
} elsif ($cmd eq "-man") { } elsif ($cmd eq "-man") {
$output_mode = "man"; $output_mode = "man";
%highlights = %highlights_man; @highlights = @highlights_man;
$blankline = $blankline_man; $blankline = $blankline_man;
} elsif ($cmd eq "-text") { } elsif ($cmd eq "-text") {
$output_mode = "text"; $output_mode = "text";
%highlights = %highlights_text; @highlights = @highlights_text;
$blankline = $blankline_text; $blankline = $blankline_text;
} elsif ($cmd eq "-docbook") { } elsif ($cmd eq "-docbook") {
$output_mode = "xml"; $output_mode = "xml";
%highlights = %highlights_xml; @highlights = @highlights_xml;
$blankline = $blankline_xml; $blankline = $blankline_xml;
} elsif ($cmd eq "-list") { } elsif ($cmd eq "-list") {
$output_mode = "list"; $output_mode = "list";
%highlights = %highlights_list; @highlights = @highlights_list;
$blankline = $blankline_list; $blankline = $blankline_list;
} elsif ($cmd eq "-gnome") { } elsif ($cmd eq "-gnome") {
$output_mode = "gnome"; $output_mode = "gnome";
%highlights = %highlights_gnome; @highlights = @highlights_gnome;
$blankline = $blankline_gnome; $blankline = $blankline_gnome;
} elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
$modulename = shift @ARGV; $modulename = shift @ARGV;
@ -2672,9 +2686,11 @@ $kernelversion = get_kernel_version();
# generate a sequence of code that will splice in highlighting information # generate a sequence of code that will splice in highlighting information
# using the s// operator. # using the s// operator.
foreach my $pattern (sort keys %highlights) { foreach my $k (keys @highlights) {
# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; my $pattern = $highlights[$k][0];
$dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; my $result = $highlights[$k][1];
# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
$dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
} }
# Read the file that maps relative names to absolute names for # Read the file that maps relative names to absolute names for