Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-21 19:41:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

kernel-doc: allow object-like macros in ReST output

Browse Source 
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: cbb4d3e651 ("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
This commit is contained in:
Randy Dunlap 2024-10-15 11:11:07 -07:00 committed by Jonathan Corbet
parent 878b56e011
commit bb8fd09e28
1 changed files with 30 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
scripts/kernel-doc
View File

@ -569,6 +569,8 @@ sub output_function_man(%) {
my %args = %{$_[0]}; my %args = %{$_[0]};
my ($parameter, $section); my ($parameter, $section);
my $count; 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"; print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
@ -600,7 +602,10 @@ sub output_function_man(%) {
$parenth = ""; $parenth = "";
} }
print ".SH ARGUMENTS\n"; $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
if ($paramcount >= 0) {
print ".SH ARGUMENTS\n";
}
foreach $parameter (@{$args{'parameterlist'}}) { foreach $parameter (@{$args{'parameterlist'}}) {
my $parameter_name = $parameter; my $parameter_name = $parameter;
$parameter_name =~ s/\[.*//; $parameter_name =~ s/\[.*//;
@ -822,10 +827,16 @@ sub output_function_rst(%) {
my $oldprefix = $lineprefix; my $oldprefix = $lineprefix;
my $signature = ""; my $signature = "";
if ($args{'functiontype'} ne "") { my $func_macro = $args{'func_macro'};
$signature = $args{'functiontype'} . " " . $args{'function'} . " ("; my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
} else {
$signature = $args{'function'} . " ("; if ($func_macro) {
$signature = $args{'function'};
} else {
if ($args{'functiontype'}) {
$signature = $args{'functiontype'} . " ";
}
$signature .= $args{'function'} . " (";
} }
my $count = 0; my $count = 0;
@ -844,7 +855,9 @@ sub output_function_rst(%) {
} }
} }
$signature .= ")"; if (!$func_macro) {
$signature .= ")";
}
if ($sphinx_major < 3) { if ($sphinx_major < 3) {
if ($args{'typedef'}) { if ($args{'typedef'}) {
@ -888,9 +901,11 @@ sub output_function_rst(%) {
# Put our descriptive text into a container (thus an HTML <div>) to help # Put our descriptive text into a container (thus an HTML <div>) to help
# set the function prototypes apart. # set the function prototypes apart.
# #
print ".. container:: kernelindent\n\n";
$lineprefix = " "; $lineprefix = " ";
print $lineprefix . "**Parameters**\n\n"; if ($paramcount >= 0) {
print ".. container:: kernelindent\n\n";
print $lineprefix . "**Parameters**\n\n";
}
foreach $parameter (@{$args{'parameterlist'}}) { foreach $parameter (@{$args{'parameterlist'}}) {
my $parameter_name = $parameter; my $parameter_name = $parameter;
$parameter_name =~ s/\[.*//; $parameter_name =~ s/\[.*//;
@ -1704,7 +1719,7 @@ sub check_return_section {
sub dump_function($$) { sub dump_function($$) {
my $prototype = shift; my $prototype = shift;
my $file = shift; my $file = shift;
my $noret = 0; my $func_macro = 0;
print_lineno($new_start_line); print_lineno($new_start_line);
@ -1769,7 +1784,7 @@ sub dump_function($$) {
# declaration_name and opening parenthesis (notice the \s+). # declaration_name and opening parenthesis (notice the \s+).
$return_type = $1; $return_type = $1;
$declaration_name = $2; $declaration_name = $2;
$noret = 1; $func_macro = 1;
} elsif ($prototype =~ m/^()($name)\s*$prototype_end/ || } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ ||
$prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ || $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
$prototype =~ m/^($type2+)\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 # of warnings goes sufficiently down, the check is only performed in
# -Wreturn mode. # -Wreturn mode.
# TODO: always perform the check. # TODO: always perform the check.
if ($Wreturn && !$noret) { if ($Wreturn && !$func_macro) {
check_return_section($file, $declaration_name, $return_type); check_return_section($file, $declaration_name, $return_type);
} }
@ -1814,7 +1829,8 @@ sub dump_function($$) {
'parametertypes' => \%parametertypes, 'parametertypes' => \%parametertypes,
'sectionlist' => \@sectionlist, 'sectionlist' => \@sectionlist,
'sections' => \%sections, 'sections' => \%sections,
'purpose' => $declaration_purpose 'purpose' => $declaration_purpose,
'func_macro' => $func_macro
}); });
} else { } else {
output_declaration($declaration_name, output_declaration($declaration_name,
@ -1827,7 +1843,8 @@ sub dump_function($$) {
'parametertypes' => \%parametertypes, 'parametertypes' => \%parametertypes,
'sectionlist' => \@sectionlist, 'sectionlist' => \@sectionlist,
'sections' => \%sections, 'sections' => \%sections,
'purpose' => $declaration_purpose 'purpose' => $declaration_purpose,
'func_macro' => $func_macro
}); });
} }
} }