Re: Doc style for method functions

[Jonathan Corbet <corbet@lwn.net>]

Simon Glass <sjg@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...

Thanks,

jon