Doc style for method functions

[Heinrich Schuchardt]

On 18.08.23 16:59, Simon Glass wrote:
> Hi Heinrich,
>
> On Thu, 17 Aug 2023 at 10:36, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
>>
>> 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.
>
> Is that the purpose of this check? Is it likely that someone would add
> a bracket immediately after a variable?

We don't want anything but a colon ':' after a structure member name.
This excludes white space, parentheses (), brackets[], and braces {} and
a lot more.

A structure member name relating to a function pointer should be the
only exception. Here we expect the parentheses and the colon to follow
immediately without white space.

Best regards

Heinrich


>
> Regards,
> Simon