summaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorRandy Dunlap <rdunlap@infradead.org>2024-10-15 11:11:07 -0700
committerJonathan Corbet <corbet@lwn.net>2024-10-17 09:33:29 -0600
commitbb8fd09e2811e2386bb40b9f0d3c7dd6e7961a1e (patch)
tree94308b147bd561337725c1e47d98d693fc2a5b4a /scripts/kernel-doc
parent878b56e011af224386464c79e3b1b1a73342d847 (diff)
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 <rdunlap@infradead.org> Cc: Horia Geanta <horia.geanta@freescale.com> Tested-by: Vlastimil Babka <vbabka@suse.cz> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241015181107.536894-1-rdunlap@infradead.org
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc43
1 files changed, 30 insertions, 13 deletions
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 <div>) 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
});
}
}