From 82f5ee35d0b960c54370a72418b9ec0dca382262 Mon Sep 17 00:00:00 2001 From: André Almeida Date: Thu, 10 Oct 2024 19:59:33 -0300 Subject: scripts/kernel-doc: Fix build time warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As stated at Documentation/kbuild/llvm.rst, to make usage of ccache one must set KBUILD_BUILD_TIMESTAMP=''. Setting this together with W=1 will trigger the following warning for every compiled file: date: invalid date ‘+%s’ This comes from kernel-doc script, that produces the following command when KBUILD_BUILD_TIMESTAMP is empty: date -d"" +%s That triggers the warning above. Add a space between the flag `-d` and the string argument to fix date command and remove the warning. Signed-off-by: André Almeida Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241010225933.166436-1-andrealmeid@igalia.com --- 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 2791f8195203..8728f9824c65 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -160,7 +160,7 @@ my @export_file_list; my @build_time; if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && - (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') { + (my $seconds = `date -d "${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') { @build_time = gmtime($seconds); } else { @build_time = localtime; -- cgit v1.2.3 From be9264110e4e874622d588a75daf930539fdf6ea Mon Sep 17 00:00:00 2001 From: Chen-Yu Tsai Date: Tue, 8 Oct 2024 16:29:04 +0800 Subject: scripts/kernel-doc: Do not track section counter across processed files The section counter tracks how many sections of kernel-doc were added. The only real use of the counter value is to check if anything was actually supposed to be output and give a warning is nothing is available. The current logic of remembering the initial value and then resetting the value then when processing each file means that if a file has the same number of sections as the previously processed one, a warning is incorrectly given. Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2") Signed-off-by: Chen-Yu Tsai Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241008082905.4005524-1-wenst@chromium.org --- scripts/kernel-doc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8728f9824c65..a84510d3cd1f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2322,7 +2322,6 @@ sub process_inline($$) { sub process_file($) { my $file; - my $initial_section_counter = $section_counter; my ($orig_file) = @_; $file = map_filename($orig_file); @@ -2360,8 +2359,7 @@ sub process_file($) { } # Make sure we got something interesting. - if ($initial_section_counter == $section_counter && $ - output_mode ne "none") { + if (!$section_counter && $output_mode ne "none") { if ($output_selection == OUTPUT_INCLUDE) { emit_warning("${file}:1", "'$_' not found\n") for keys %function_table; -- cgit v1.2.3 From bb8fd09e2811e2386bb40b9f0d3c7dd6e7961a1e Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 15 Oct 2024 11:11:07 -0700 Subject: kernel-doc: allow object-like macros in ReST output output_function_rst() does not handle object-like macros. It presents a trailing "()" while output_function_man() handles these macros correctly. Update output_function_rst() to handle object-like macros. Don't show the "Parameters" heading if there are no parameters. For output_function_man(), don't show the "ARGUMENTS" heading if there are no parameters. I have tested this quite a bit with my ad hoc test files for both ReST and man format outputs. The generated output looks good. Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") Signed-off-by: Randy Dunlap Cc: Horia Geanta Tested-by: Vlastimil Babka Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241015181107.536894-1-rdunlap@infradead.org --- scripts/kernel-doc | 43 ++++++++++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 13 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a84510d3cd1f..f66070176ba3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -569,6 +569,8 @@ sub output_function_man(%) { my %args = %{$_[0]}; my ($parameter, $section); my $count; + my $func_macro = $args{'func_macro'}; + my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n"; @@ -600,7 +602,10 @@ sub output_function_man(%) { $parenth = ""; } - print ".SH ARGUMENTS\n"; + $paramcount = $#{$args{'parameterlist'}}; # -1 is empty + if ($paramcount >= 0) { + print ".SH ARGUMENTS\n"; + } foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; @@ -822,10 +827,16 @@ sub output_function_rst(%) { my $oldprefix = $lineprefix; my $signature = ""; - if ($args{'functiontype'} ne "") { - $signature = $args{'functiontype'} . " " . $args{'function'} . " ("; - } else { - $signature = $args{'function'} . " ("; + my $func_macro = $args{'func_macro'}; + my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty + + if ($func_macro) { + $signature = $args{'function'}; + } else { + if ($args{'functiontype'}) { + $signature = $args{'functiontype'} . " "; + } + $signature .= $args{'function'} . " ("; } my $count = 0; @@ -844,7 +855,9 @@ sub output_function_rst(%) { } } - $signature .= ")"; + if (!$func_macro) { + $signature .= ")"; + } if ($sphinx_major < 3) { if ($args{'typedef'}) { @@ -888,9 +901,11 @@ sub output_function_rst(%) { # Put our descriptive text into a container (thus an HTML
) to help # set the function prototypes apart. # - print ".. container:: kernelindent\n\n"; $lineprefix = " "; - print $lineprefix . "**Parameters**\n\n"; + if ($paramcount >= 0) { + print ".. container:: kernelindent\n\n"; + print $lineprefix . "**Parameters**\n\n"; + } foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; @@ -1704,7 +1719,7 @@ sub check_return_section { sub dump_function($$) { my $prototype = shift; my $file = shift; - my $noret = 0; + my $func_macro = 0; print_lineno($new_start_line); @@ -1769,7 +1784,7 @@ sub dump_function($$) { # declaration_name and opening parenthesis (notice the \s+). $return_type = $1; $declaration_name = $2; - $noret = 1; + $func_macro = 1; } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ || $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ || $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) { @@ -1796,7 +1811,7 @@ sub dump_function($$) { # of warnings goes sufficiently down, the check is only performed in # -Wreturn mode. # TODO: always perform the check. - if ($Wreturn && !$noret) { + if ($Wreturn && !$func_macro) { check_return_section($file, $declaration_name, $return_type); } @@ -1814,7 +1829,8 @@ sub dump_function($$) { 'parametertypes' => \%parametertypes, 'sectionlist' => \@sectionlist, 'sections' => \%sections, - 'purpose' => $declaration_purpose + 'purpose' => $declaration_purpose, + 'func_macro' => $func_macro }); } else { output_declaration($declaration_name, @@ -1827,7 +1843,8 @@ sub dump_function($$) { 'parametertypes' => \%parametertypes, 'sectionlist' => \@sectionlist, 'sections' => \%sections, - 'purpose' => $declaration_purpose + 'purpose' => $declaration_purpose, + 'func_macro' => $func_macro }); } } -- cgit v1.2.3