From 23aebb3c05f3b3fb06a68bf6b1539a05a5f8aaab Mon Sep 17 00:00:00 2001 From: Danilo Cesar Lemes de Paula Date: Tue, 1 Sep 2015 14:44:14 -0300 Subject: scripts/kernel-doc: Processing -nofunc for functions only Docproc processes the EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to avoid duplicated documentation in the next call. It works for most of the cases, but there are some specific situations where a struct has the same name of an already-exported function. Current kernel-doc behavior ignores those structs and does not add them to the final documentation. This patch fixes it. This is unusual, the only case I've found is the drm_modeset_lock (function and struct) defined in drm_modeset_lock.h and drm_modeset_lock.c. Considering this, it should only affect the DRM documentation by including struct drm_modeset_lock to the final Docbook. Signed-off-by: Danilo Cesar Lemes de Paula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9a08fb5c1af6..532d8cd2543f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1746,7 +1746,7 @@ sub output_declaration { my $func = "output_${functype}_$output_mode"; if (($function_only==0) || ( $function_only == 1 && defined($function_table{$name})) || - ( $function_only == 2 && !defined($function_table{$name}))) + ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name})))) { &$func(@_); $section_counter++; -- cgit v1.2.3-55-g7522 From 68f86662380c343317325c024d6a35221f1908ac Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Tue, 1 Sep 2015 23:48:49 +0100 Subject: Documentation: Avoid creating man pages in source tree Currently kernel-doc generates a dummy DocBook file when asked to convert a C source file with no structured comments. For an out-of-tree build (objtree != srctree), the title of the output file is the absolute path name of the C source file, which later results in a manual page being created alongside the C source file. Change the title to be a relative path. Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 532d8cd2543f..61b4aa86fcdf 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2391,12 +2391,13 @@ sub process_file($) { my $descr; my $in_purpose = 0; my $initial_section_counter = $section_counter; + my ($orig_file) = @_; if (defined($ENV{'SRCTREE'})) { - $file = "$ENV{'SRCTREE'}" . "/" . "@_"; + $file = "$ENV{'SRCTREE'}" . "/" . $orig_file; } else { - $file = "@_"; + $file = $orig_file; } if (defined($source_map{$file})) { $file = $source_map{$file}; @@ -2640,7 +2641,7 @@ sub process_file($) { print "\n"; print " \n"; print " \n"; - print " ${file}\n"; + print " ${orig_file}\n"; print " \n"; print " \n"; print " Document generation inconsistency\n"; @@ -2654,7 +2655,7 @@ sub process_file($) { print " \n"; print " The template for this document tried to insert\n"; print " the structured comment from the file\n"; - print " ${file} at this point,\n"; + print " ${orig_file} at this point,\n"; print " but none was found.\n"; print " This dummy section is inserted to allow\n"; print " generation to continue.\n"; -- cgit v1.2.3-55-g7522 From 4d73270192ec8238135d9fb65b49f6f42f50818d Mon Sep 17 00:00:00 2001 From: Danilo Cesar Lemes de Paula Date: Mon, 7 Sep 2015 17:01:59 -0300 Subject: 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: - @device_for_each_child 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 Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 104 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 60 insertions(+), 44 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 61b4aa86fcdf..25029bcaf583 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -206,59 +206,73 @@ my $type_env = '(\$\w+)'; # One for each output format # these work fairly well -my %highlights_html = ( $type_constant, "\$1", - $type_func, "\$1", - $type_struct_xml, "\$1", - $type_env, "\$1", - $type_param, "\$1" ); +my @highlights_html = ( + [$type_constant, "\$1"], + [$type_func, "\$1"], + [$type_struct_xml, "\$1"], + [$type_env, "\$1"], + [$type_param, "\$1"] + ); my $local_lt = "\\\\\\\\lt:"; my $local_gt = "\\\\\\\\gt:"; my $blankline_html = $local_lt . "p" . $local_gt; # was "

" # html version 5 -my %highlights_html5 = ( $type_constant, "\$1", - $type_func, "\$1", - $type_struct_xml, "\$1", - $type_env, "\$1", - $type_param, "\$1" ); +my @highlights_html5 = ( + [$type_constant, "\$1"], + [$type_func, "\$1"], + [$type_struct_xml, "\$1"], + [$type_env, "\$1"], + [$type_param, "\$1]"] + ); my $blankline_html5 = $local_lt . "br /" . $local_gt; # XML, docbook format -my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", - $type_constant, "\$1", - $type_func, "\$1", - $type_struct_xml, "\$1", - $type_env, "\$1", - $type_param, "\$1" ); +my @highlights_xml = ( + ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"], + [$type_constant, "\$1"], + [$type_struct_xml, "\$1"], + [$type_param, "\$1"], + [$type_func, "\$1"], + [$type_env, "\$1"] + ); my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; # gnome, docbook format -my %highlights_gnome = ( $type_constant, "\$1", - $type_func, "\$1", - $type_struct, "\$1", - $type_env, "\$1", - $type_param, "\$1" ); +my @highlights_gnome = ( + [$type_constant, "\$1"], + [$type_func, "\$1"], + [$type_struct, "\$1"], + [$type_env, "\$1"], + [$type_param, "\$1" ] + ); my $blankline_gnome = "\n"; # these are pretty rough -my %highlights_man = ( $type_constant, "\$1", - $type_func, "\\\\fB\$1\\\\fP", - $type_struct, "\\\\fI\$1\\\\fP", - $type_param, "\\\\fI\$1\\\\fP" ); +my @highlights_man = ( + [$type_constant, "\$1"], + [$type_func, "\\\\fB\$1\\\\fP"], + [$type_struct, "\\\\fI\$1\\\\fP"], + [$type_param, "\\\\fI\$1\\\\fP"] + ); my $blankline_man = ""; # text-mode -my %highlights_text = ( $type_constant, "\$1", - $type_func, "\$1", - $type_struct, "\$1", - $type_param, "\$1" ); +my @highlights_text = ( + [$type_constant, "\$1"], + [$type_func, "\$1"], + [$type_struct, "\$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 @highlights_list = ( + [$type_constant, "\$1"], + [$type_func, "\$1"], + [$type_struct, "\$1"], + [$type_param, "\$1"] + ); my $blankline_list = ""; # read arguments @@ -273,7 +287,7 @@ my $verbose = 0; my $output_mode = "man"; my $output_preformatted = 0; my $no_doc_sections = 0; -my %highlights = %highlights_man; +my @highlights = @highlights_man; my $blankline = $blankline_man; my $modulename = "Kernel API"; my $function_only = 0; @@ -374,31 +388,31 @@ while ($ARGV[0] =~ m/^-(.*)/) { my $cmd = shift @ARGV; if ($cmd eq "-html") { $output_mode = "html"; - %highlights = %highlights_html; + @highlights = @highlights_html; $blankline = $blankline_html; } elsif ($cmd eq "-html5") { $output_mode = "html5"; - %highlights = %highlights_html5; + @highlights = @highlights_html5; $blankline = $blankline_html5; } elsif ($cmd eq "-man") { $output_mode = "man"; - %highlights = %highlights_man; + @highlights = @highlights_man; $blankline = $blankline_man; } elsif ($cmd eq "-text") { $output_mode = "text"; - %highlights = %highlights_text; + @highlights = @highlights_text; $blankline = $blankline_text; } elsif ($cmd eq "-docbook") { $output_mode = "xml"; - %highlights = %highlights_xml; + @highlights = @highlights_xml; $blankline = $blankline_xml; } elsif ($cmd eq "-list") { $output_mode = "list"; - %highlights = %highlights_list; + @highlights = @highlights_list; $blankline = $blankline_list; } elsif ($cmd eq "-gnome") { $output_mode = "gnome"; - %highlights = %highlights_gnome; + @highlights = @highlights_gnome; $blankline = $blankline_gnome; } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document $modulename = shift @ARGV; @@ -2672,9 +2686,11 @@ $kernelversion = get_kernel_version(); # generate a sequence of code that will splice in highlighting information # using the s// operator. -foreach my $pattern (sort keys %highlights) { -# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; - $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; +foreach my $k (keys @highlights) { + my $pattern = $highlights[$k][0]; + 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 -- cgit v1.2.3-55-g7522