On 10/14/24 07:13, Randy Dunlap wrote: > output_function_rst() does not handle object-like macros. It presents > a trailing "()" while output_function_man() handles these macros > correctly. Thanks! > Update output_function_rst() to handle object-like macros. > Don't show the "Parameters" heading if there are no parameters. > > For output_function_man(), do 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. > > However, I am seeing one problem that I don't have any idea about and > would appreciate some assistance, even just email commentary about it. > The output now includes around 100 warnings like these examples: > > Documentation/core-api/mm-api:37: ../include/linux/slab.h:154: WARNING: Inline literal start-string without end-string. [docutils] > Documentation/core-api/mm-api:37: ../include/linux/slab.h:192: WARNING: Inline literal start-string without end-string. [docutils] To clarify, I assume this part only happens with my patch that motivated this? https://lore.kernel.org/all/20241009142936.56092-2-vbabka@xxxxxxx/ Also can you clarify whether these docs should look like: /** * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ per Documentation/doc-guide/kernel-doc.rst or /** * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - Initializes struct drm_plane_helper_funcs * for VRAM handling as it is in the actual file include/drm/drm_gem_vram_helper.h i.e. if that "define" keyword is needed, or it doesn't matter? Thanks, Vlastimil > and > Documentation/driver-api/device-io.rst:: ERROR: Anonymous hyperlink mismatch: 16 references but 0 targets. > See "backrefs" attribute for IDs. [docutils] > > Does this mean that I am now generated some garbage and feeding it to > docutils? > > Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") > Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> > Cc: Horia Geanta <horia.geanta@xxxxxxxxxxxxx> > Cc: Jonathan Corbet <corbet@xxxxxxx> > Cc: Vlastimil Babka <vbabka@xxxxxxx> > --- > Cc: linux-doc@xxxxxxxxxxxxxxx > > scripts/kernel-doc | 35 ++++++++++++++++++++++++----------- > 1 file changed, 24 insertions(+), 11 deletions(-) > > --- linux-next-20241009.orig/scripts/kernel-doc > +++ linux-next-20241009/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'}}; # treat -1 as 0 > > print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n"; > > @@ -600,7 +602,9 @@ sub output_function_man(%) { > $parenth = ""; > } > > - print ".SH ARGUMENTS\n"; > + if ($paramcount = $#{$args{'parameterlist'}} > 0) { > + print ".SH ARGUMENTS\n"; > + } > foreach $parameter (@{$args{'parameterlist'}}) { > my $parameter_name = $parameter; > $parameter_name =~ s/\[.*//; > @@ -822,10 +826,13 @@ sub output_function_rst(%) { > my $oldprefix = $lineprefix; > > my $signature = ""; > - if ($args{'functiontype'} ne "") { > + my $func_macro = $args{'func_macro'}; > + my $paramcount = $#{$args{'parameterlist'}}; # treat -1 as 0 > + > + if ($func_macro) { > + $signature = $args{'function'} . " "; > + } else { > $signature = $args{'functiontype'} . " " . $args{'function'} . " ("; > - } else { > - $signature = $args{'function'} . " ("; > } > > my $count = 0; > @@ -844,7 +851,9 @@ sub output_function_rst(%) { > } > } > > - $signature .= ")"; > + if (!$func_macro) { > + $signature .= ")"; > + } > > if ($sphinx_major < 3) { > if ($args{'typedef'}) { > @@ -890,7 +899,9 @@ sub output_function_rst(%) { > # > print ".. container:: kernelindent\n\n"; > $lineprefix = " "; > - print $lineprefix . "**Parameters**\n\n"; > + if ($paramcount > 0) { > + print $lineprefix . "**Parameters**\n\n"; > + } > foreach $parameter (@{$args{'parameterlist'}}) { > my $parameter_name = $parameter; > $parameter_name =~ s/\[.*//; > @@ -1704,7 +1715,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 +1780,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 +1807,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 +1825,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 +1839,8 @@ sub dump_function($$) { > 'parametertypes' => \%parametertypes, > 'sectionlist' => \@sectionlist, > 'sections' => \%sections, > - 'purpose' => $declaration_purpose > + 'purpose' => $declaration_purpose, > + 'func_macro' => $func_macro > }); > } > }
