Doc style for method functions

[Simon Glass]

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?

Regards,
Simon