Doc style for method functions

[Heinrich Schuchardt]

On 16.08.23 19:47, Simon Glass wrote:
> Hi Jonathan,
>
> On Wed, 16 Aug 2023 at 11:15, Jonathan Corbet <corbet at lwn.net> wrote:
>>
>> Simon Glass <sjg at chromium.org> writes:
>>
>>> Hi Jonathan,
>>>
>>> I would like to do something like this:
>>>
>>> struct part_driver {
>>>     /**
>>>      * get_info() - Get information about a partition
>>>
>>>                ^ causes error
>>>
>>>      *
>>>      * @desc: Block device descriptor
>>>      * @part: Partition number (1 = first)
>>>      * @info: Returns partition information
>>>      */
>>>     int (*get_info)(struct blk_desc *desc, int part, struct
>>> disk_partition *info);
>>> ...
>>> };
>>>
>>> But this gives:
>>>
>>> scripts/kernel-doc:292:
>>>     print STDERR "Incorrect use of kernel-doc format: $_";
>>>
>>> Without the brackets on get_info() it works OK. What is the purpose of
>>> that check, please?
>>
>> That's how the kerneldoc syntax was defined, well before my time as the
>> maintainer.  This could be relaxed, I guess, but one would have to look
>> at the parsing code to be sure that the right thing happens all the way
>> through the process.  I'm not entirely sure it's worth it...
>
> I see. It is inconsistent, since we use () after normal functions.
>
> I think I can fix it just by removing that check.
>
> Regards,
> Simon

If the structure element in not a function pointer, we probably still
want to forbid adding parentheses. Just dropping the check might not be
the solution.

Best regards

Heinrich