On 10/14/24 8:48 AM, Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> writes:
>
>> 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(), 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]
>
> That comes down to this in the kernel-doc output:
>
>> .. c:macro:: DRM_SCHED_FENCE_DONT_PIPELINE
>>
>> ``DRM_SCHED_FENCE_DONT_PIPELINE ``
>>
>> Prefent dependency pipelining
>>
>
> Sphinx is, as we know, weird about white space, so the blank before the
> closing `` makes it unhappy.
>
> The attached patch on top of yours makes it go away - but there are some
> other weird warnings, like:
>
>> /stuff/k/git/kernel/Documentation/gpu/imagination/uapi:169:
>> ./drivers/gpu/drm/imagination/pvr_device.h:686: ERROR: Unknown target name:
>> "static_expr".
>
> ...that I haven't been able to track down yet.
>
> Thanks for working on this,
Oops, that is picky. Thanks for the fix.
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 78373af6679e..aaf29b11b3bc 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -830,7 +830,7 @@ sub output_function_rst(%) {
> my $paramcount = $#{$args{'parameterlist'}}; # treat -1 as 0
>
> if ($func_macro) {
> - $signature = $args{'function'} . " ";
> + $signature = $args{'function'};
> } else {
> $signature = $args{'functiontype'} . " " . $args{'function'} . " (";
> }
>
--
~Randy
