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

[Randy Dunlap <rdunlap@xxxxxxxxxxxxx>]

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@xxxxxxx> 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.


"""
SLAB_TYPESAFE_BY_RCU
``SLAB_TYPESAFE_BY_RCU ``

WARNING READ THIS!

Description
"""

---
From: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
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@xxxxxxxxxxxxx>
Cc: Horia Geanta <horia.geanta@xxxxxxxxxxxxx>
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: linux-doc@xxxxxxxxxxxxxxx
Cc: Vlastimil Babka <vbabka@xxxxxxx>
---
 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/\[.*//;