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/kernel-doc') 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 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/kernel-doc') 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 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/kernel-doc') 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 From 3a80a766328fe73df5951639b5c9013ddba6efec Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Oct 2015 15:21:44 -0300 Subject: kernel-doc: Add a parser for function typedefs The current typedef parser only works for non-function typedefs. As we need to also document some function typedefs, add a parser for it. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9a08fb5c1af6..55ce47ffa02d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1886,6 +1886,18 @@ sub dump_typedef($$) { 'purpose' => $declaration_purpose }); } + elsif ($x =~ /typedef\s+\w+\s*\(\*\s*(\w\S+)\s*\)\s*\(/) { # functions + $declaration_name = $1; + + output_declaration($declaration_name, + 'typedef', + {'typedef' => $declaration_name, + 'module' => $modulename, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } else { print STDERR "${file}:$.: error: Cannot parse typedef!\n"; ++$errors; -- cgit v1.2.3 From 837664528e17380cfacfb766de37df31572f07a0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Oct 2015 16:14:45 -0300 Subject: kernel-doc: better format typedef function output A typedef function looks more likely a function and not a normal typedef. Change the code to use the output_function_*, in order to properly parse the function prototype parameters. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 55ce47ffa02d..0276d2b5eefe 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1869,24 +1869,37 @@ sub dump_typedef($$) { my $file = shift; $x =~ s@/\*.*?\*/@@gos; # strip comments. - while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { - $x =~ s/\(*.\)\s*;$/;/; - $x =~ s/\[*.\]\s*;$/;/; - } - if ($x =~ /typedef.*\s+(\w+)\s*;/) { - $declaration_name = $1; + # Parse function prototypes + if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) { + # Function typedefs + $return_type = $1; + $declaration_name = $2; + my $args = $3; + + create_parameterlist($args, ',', $file); output_declaration($declaration_name, - 'typedef', - {'typedef' => $declaration_name, + 'function', + {'function' => $declaration_name, 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, 'sectionlist' => \@sectionlist, 'sections' => \%sections, 'purpose' => $declaration_purpose }); + return; + } + + while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { + $x =~ s/\(*.\)\s*;$/;/; + $x =~ s/\[*.\]\s*;$/;/; } - elsif ($x =~ /typedef\s+\w+\s*\(\*\s*(\w\S+)\s*\)\s*\(/) { # functions + + if ($x =~ /typedef.*\s+(\w+)\s*;/) { $declaration_name = $1; output_declaration($declaration_name, -- cgit v1.2.3 From 0d8c39e6c6dd97fc7fc40e93b44d76bb6dc4d4e4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 5 Oct 2015 09:03:48 -0300 Subject: DocBook: Fix kernel-doc to be case-insensitive for private: On some places, people could use Private: to tag the private fields of an struct. So, be case-insensitive when parsing "private:" meta-tag. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 25029bcaf583..80428be3411a 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1805,8 +1805,8 @@ sub dump_struct($$) { $nested = $1; # ignore members marked private: - $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos; - $members =~ s/\/\*\s*private:.*//gos; + $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; + $members =~ s/\/\*\s*private:.*//gosi; # strip comments: $members =~ s/\/\*.*?\*\///gos; $nested =~ s/\/\*.*?\*\///gos; -- cgit v1.2.3 From 1ef0623371e0a39a476fb05e575089cf48178f5c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 17 Nov 2015 13:29:49 -0200 Subject: kernel-doc: Make it compatible with Perl versions below 5.12 again Changeset 4d73270192ec('scripts/kernel-doc: Replacing highlights hash by an array') broke compatibility of the kernel-doc script with older versions of perl by using "keys ARRAY" syntax with is available only on Perl 5.12 or newer, according with: http://perldoc.perl.org/functions/keys.html Restore backward compatibility by replacing "foreach my $k (keys ARRAY)" by a C-like variant: "for (my $k = 0; $k < !ARRAY; $k++)" Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 125b906cd1d4..638a38e1b419 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2711,7 +2711,7 @@ $kernelversion = get_kernel_version(); # generate a sequence of code that will splice in highlighting information # using the s// operator. -foreach my $k (keys @highlights) { +for (my $k = 0; $k < @highlights; $k++) { my $pattern = $highlights[$k][0]; my $result = $highlights[$k][1]; # print STDERR "scanning pattern:$pattern, highlight:($result)\n"; -- cgit v1.2.3