Doc style for method functions

[Simon Glass]

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