Doc style for method functions

Doc style for method functions

[Simon Glass]

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?

Regards,
Simon

Re: Doc style for method functions

[Jonathan Corbet]

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

Re: Doc style for method functions

[Simon Glass]

Hi Jonathan,

On Wed, 16 Aug 2023 at 11:15, Jonathan Corbet <corbet@lwn.net> wrote:
>
> 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...

I see. It is inconsistent, since we use () after normal functions.

I think I can fix it just by removing that check.

Regards,
Simon

Re: 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@lwn.net> wrote:
>>
>> 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...
>
> 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

Re: Doc style for method functions

[Simon Glass]

Hi Heinrich,

On Thu, 17 Aug 2023 at 10:36, Heinrich Schuchardt <xypron.glpk@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@lwn.net> wrote:
> >>
> >> 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...
> >
> > 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

Re: 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@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@lwn.net> wrote:
>>>>
>>>> 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...
>>>
>>> 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