Re: [partial fix] Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Randy Dunlap <rdunlap@infradead.org>]

On 10/10/24 8:07 PM, Randy Dunlap wrote:
> 
> 
> On 10/10/24 4:54 PM, Randy Dunlap wrote:
>>
>>
>> On 10/10/24 4:43 PM, Randy Dunlap wrote:
>>>
>>>
>>> On 10/9/24 10:06 PM, Randy Dunlap wrote:
>>>>
>>>>
>>>> On 10/9/24 3:02 PM, Randy Dunlap wrote:
>>>>>
>>>>>
>>>>> On 10/9/24 9:49 AM, Jonathan Corbet wrote:
>>>>>> Vlastimil Babka <vbabka@suse.cz> writes:
>>>>>>
>>>
>>> The main problem is that output_function_rst() does not support object-like macros while
>>> output_function_man() does.  There is still a bunch of sphinx_version handling that I know
>>> nothing about, so the present output (after my trivial patch) leaves more to be done.
>>>
>>> Well, the *main* problem is that the output is not consistent. Sometimes my tests don't fail
>>> as they did at first.
>>>
>>>
>>> This patch drops the trailing "()" for object-like macros in output_function_rst()
>>> but there is still more to be done.
>>>
>>> ---------------------
> 
> This one mostly works for me although I don't care for the second line
> here. I guess it has something to do with cross-referencing(?), but IDK.
> 

That seems to be normal but this patch now causes regressions for macros that
do have parameters. Back to searching...

> 
> """
> SLAB_TYPESAFE_BY_RCU
> ``SLAB_TYPESAFE_BY_RCU ``
> 
> WARNING READ THIS!
> 
> Description
> """
> 
> ---
> From: Randy Dunlap <rdunlap@infradead.org>
> Subject: [PATCH] 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.
> 
> Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Horia Geanta <horia.geanta@freescale.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Vlastimil Babka <vbabka@suse.cz>
> ---
>  scripts/kernel-doc |   13 ++++++++++---
>  1 file changed, 10 insertions(+), 3 deletions(-)
> 
> --- linux-next-20241009.orig/scripts/kernel-doc
> +++ linux-next-20241009/scripts/kernel-doc
> @@ -822,10 +822,13 @@ sub output_function_rst(%) {
>      my $oldprefix = $lineprefix;
>  
>      my $signature = "";
> +    my $noret = 0;
> +
>      if ($args{'functiontype'} ne "") {
>          $signature = $args{'functiontype'} . " " . $args{'function'} . " (";
>      } else {
> -        $signature = $args{'function'} . " (";
> +        $signature = $args{'function'} . " ";
> +    	$noret = 1;
>      }
>  
>      my $count = 0;
> @@ -844,7 +847,9 @@ sub output_function_rst(%) {
>          }
>      }
>  
> -    $signature .= ")";
> +    if (!$noret) {
> +    	$signature .= ")";
> +    }
>  
>      if ($sphinx_major < 3) {
>          if ($args{'typedef'}) {
> @@ -890,7 +895,9 @@ sub output_function_rst(%) {
>      #
>      print ".. container:: kernelindent\n\n";
>      $lineprefix = "  ";
> -    print $lineprefix . "**Parameters**\n\n";
> +	if (!$noret) {
> +   		print $lineprefix . "**Parameters**\n\n";
> +    }
>      foreach $parameter (@{$args{'parameterlist'}}) {
>          my $parameter_name = $parameter;
>          $parameter_name =~ s/\[.*//;
> 
> 

-- 
~Randy