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:
>>>
>>>> Thanks for the hints. I hope if we can agree that documenting the macros was
>>>> intended to be supported, doesn't break the build (there are users already)
>>>> and has only those minor rendering issues, it can be used?
>>>
>>> I'd totally forgotten that this was supposed to work.
>>>
>>> Yes it can be used... $WE just need to find a way to make it work
>>> properly.
>>
>> The code probably isn't expecting a macro on the right side. I'll take a look,
>> but no promises.
>>
> That would have been too simple.
> I haven't found the problem yet. Ran out of time. Will continue on it tommorrow/Thursday.
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.
---------------------
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 | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
--- linux-next-20241009.orig/scripts/kernel-doc
+++ linux-next-20241009/scripts/kernel-doc
@@ -822,10 +822,12 @@ sub output_function_rst(%) {
my $oldprefix = $lineprefix;
my $signature = "";
+ my $noret = $signature eq "";
+
if ($args{'functiontype'} ne "") {
$signature = $args{'functiontype'} . " " . $args{'function'} . " (";
} else {
- $signature = $args{'function'} . " (";
+ $signature = $args{'function'} . " ";
}
my $count = 0;
@@ -844,7 +846,9 @@ sub output_function_rst(%) {
}
}
- $signature .= ")";
+ if (!$noret) {
+ $signature .= ")";
+ }
if ($sphinx_major < 3) {
if ($args{'typedef'}) {
