[PATCH] platform/x86/intel/vsec: correct kernel-doc comments

[PATCH] platform/x86/intel/vsec: correct kernel-doc comments

[Randy Dunlap]

Fix kernel-doc warnings in intel_vsec.h to eliminate all kernel-doc
warnings:

Warning: include/linux/intel_vsec.h:92 struct member 'read_telem' not
 described in 'pmt_callbacks'
Warning: include/linux/intel_vsec.h:146 expecting prototype for struct
 intel_sec_device.  Prototype was for struct intel_vsec_device instead
Warning: include/linux/intel_vsec.h:146 struct member 'priv_data_size'
 not described in 'intel_vsec_device'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: David E. Box <david.e.box@linux.intel.com>
Cc: Hans de Goede <hansg@kernel.org>
Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
Cc: platform-driver-x86@vger.kernel.org
---
 include/linux/intel_vsec.h |    7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

--- linux-next-20251201.orig/include/linux/intel_vsec.h
+++ linux-next-20251201/include/linux/intel_vsec.h
@@ -80,8 +80,8 @@ enum intel_vsec_quirks {
 
 /**
  * struct pmt_callbacks - Callback infrastructure for PMT devices
- * ->read_telem() when specified, called by client driver to access PMT data (instead
- * of direct copy).
+ * @read_telem: when specified, called by client driver to access PMT
+ * data (instead of direct copy).
  * @pdev:  PCI device reference for the callback's use
  * @guid:  ID of data to acccss
  * @data:  buffer for the data to be copied
@@ -120,7 +120,7 @@ struct intel_vsec_platform_info {
 };
 
 /**
- * struct intel_sec_device - Auxbus specific device information
+ * struct intel_vsec_device - Auxbus specific device information
  * @auxdev:        auxbus device struct for auxbus access
  * @pcidev:        pci device associated with the device
  * @resource:      any resources shared by the parent
@@ -128,6 +128,7 @@ struct intel_vsec_platform_info {
  * @num_resources: number of resources
  * @id:            xarray id
  * @priv_data:     any private data needed
+ * @priv_data_size: size of private data area
  * @quirks:        specified quirks
  * @base_addr:     base address of entries (if specified)
  * @cap_id:        the enumerated id of the vsec feature

Re: [PATCH] platform/x86/intel/vsec: correct kernel-doc comments

[Ilpo Järvinen]

[-- Attachment #1: Type: text/plain, Size: 2417 bytes --]

On Sun, 14 Dec 2025, Randy Dunlap wrote:

> Fix kernel-doc warnings in intel_vsec.h to eliminate all kernel-doc
> warnings:
> 
> Warning: include/linux/intel_vsec.h:92 struct member 'read_telem' not
>  described in 'pmt_callbacks'
> Warning: include/linux/intel_vsec.h:146 expecting prototype for struct
>  intel_sec_device.  Prototype was for struct intel_vsec_device instead
> Warning: include/linux/intel_vsec.h:146 struct member 'priv_data_size'
>  not described in 'intel_vsec_device'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: David E. Box <david.e.box@linux.intel.com>
> Cc: Hans de Goede <hansg@kernel.org>
> Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
> Cc: platform-driver-x86@vger.kernel.org
> ---
>  include/linux/intel_vsec.h |    7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> --- linux-next-20251201.orig/include/linux/intel_vsec.h
> +++ linux-next-20251201/include/linux/intel_vsec.h
> @@ -80,8 +80,8 @@ enum intel_vsec_quirks {
>  
>  /**
>   * struct pmt_callbacks - Callback infrastructure for PMT devices
> - * ->read_telem() when specified, called by client driver to access PMT data (instead
> - * of direct copy).
> + * @read_telem: when specified, called by client driver to access PMT
> + * data (instead of direct copy).
>   * @pdev:  PCI device reference for the callback's use
>   * @guid:  ID of data to acccss
>   * @data:  buffer for the data to be copied

Is it correct for kerneldoc to have the rest as @pdev, @guid, etc.,
they are parameters to the callback, not members of this struct?

> @@ -120,7 +120,7 @@ struct intel_vsec_platform_info {
>  };
>  
>  /**
> - * struct intel_sec_device - Auxbus specific device information
> + * struct intel_vsec_device - Auxbus specific device information
>   * @auxdev:        auxbus device struct for auxbus access
>   * @pcidev:        pci device associated with the device
>   * @resource:      any resources shared by the parent
> @@ -128,6 +128,7 @@ struct intel_vsec_platform_info {
>   * @num_resources: number of resources
>   * @id:            xarray id
>   * @priv_data:     any private data needed
> + * @priv_data_size: size of private data area
>   * @quirks:        specified quirks
>   * @base_addr:     base address of entries (if specified)
>   * @cap_id:        the enumerated id of the vsec feature
> 

-- 
 i.

Re: [PATCH] platform/x86/intel/vsec: correct kernel-doc comments

[Randy Dunlap]

Hi Ilpo,

On 12/15/25 6:10 AM, Ilpo Järvinen wrote:
> On Sun, 14 Dec 2025, Randy Dunlap wrote:
> 
>> Fix kernel-doc warnings in intel_vsec.h to eliminate all kernel-doc
>> warnings:
>>
>> Warning: include/linux/intel_vsec.h:92 struct member 'read_telem' not
>>  described in 'pmt_callbacks'
>> Warning: include/linux/intel_vsec.h:146 expecting prototype for struct
>>  intel_sec_device.  Prototype was for struct intel_vsec_device instead
>> Warning: include/linux/intel_vsec.h:146 struct member 'priv_data_size'
>>  not described in 'intel_vsec_device'
>>
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>> Cc: David E. Box <david.e.box@linux.intel.com>
>> Cc: Hans de Goede <hansg@kernel.org>
>> Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
>> Cc: platform-driver-x86@vger.kernel.org
>> ---
>>  include/linux/intel_vsec.h |    7 ++++---
>>  1 file changed, 4 insertions(+), 3 deletions(-)
>>
>> --- linux-next-20251201.orig/include/linux/intel_vsec.h
>> +++ linux-next-20251201/include/linux/intel_vsec.h
>> @@ -80,8 +80,8 @@ enum intel_vsec_quirks {
>>  
>>  /**
>>   * struct pmt_callbacks - Callback infrastructure for PMT devices
>> - * ->read_telem() when specified, called by client driver to access PMT data (instead
>> - * of direct copy).
>> + * @read_telem: when specified, called by client driver to access PMT
>> + * data (instead of direct copy).
>>   * @pdev:  PCI device reference for the callback's use
>>   * @guid:  ID of data to acccss
>>   * @data:  buffer for the data to be copied
> 
> Is it correct for kerneldoc to have the rest as @pdev, @guid, etc.,
> they are parameters to the callback, not members of this struct?

No, it's not correct. We get away with it in several kernel source files
because scripts/kernel-doc doesn't check/notice that.

Would you prefer to have them there but without the leading '@' sign?
Or completely delete those lines?
IMO they are useful/informative, so I would rather not delete them.

>> @@ -120,7 +120,7 @@ struct intel_vsec_platform_info {
>>  };
>>  
>>  /**
>> - * struct intel_sec_device - Auxbus specific device information
>> + * struct intel_vsec_device - Auxbus specific device information
>>   * @auxdev:        auxbus device struct for auxbus access
>>   * @pcidev:        pci device associated with the device
>>   * @resource:      any resources shared by the parent
>> @@ -128,6 +128,7 @@ struct intel_vsec_platform_info {
>>   * @num_resources: number of resources
>>   * @id:            xarray id
>>   * @priv_data:     any private data needed
>> + * @priv_data_size: size of private data area
>>   * @quirks:        specified quirks
>>   * @base_addr:     base address of entries (if specified)
>>   * @cap_id:        the enumerated id of the vsec feature
>>
> 

thanks.
-- 
~Randy

Re: [PATCH] platform/x86/intel/vsec: correct kernel-doc comments

[Ilpo Järvinen]

[-- Attachment #1: Type: text/plain, Size: 3352 bytes --]

On Mon, 15 Dec 2025, Randy Dunlap wrote:

> Hi Ilpo,
> 
> On 12/15/25 6:10 AM, Ilpo Järvinen wrote:
> > On Sun, 14 Dec 2025, Randy Dunlap wrote:
> > 
> >> Fix kernel-doc warnings in intel_vsec.h to eliminate all kernel-doc
> >> warnings:
> >>
> >> Warning: include/linux/intel_vsec.h:92 struct member 'read_telem' not
> >>  described in 'pmt_callbacks'
> >> Warning: include/linux/intel_vsec.h:146 expecting prototype for struct
> >>  intel_sec_device.  Prototype was for struct intel_vsec_device instead
> >> Warning: include/linux/intel_vsec.h:146 struct member 'priv_data_size'
> >>  not described in 'intel_vsec_device'
> >>
> >> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> >> ---
> >> Cc: David E. Box <david.e.box@linux.intel.com>
> >> Cc: Hans de Goede <hansg@kernel.org>
> >> Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
> >> Cc: platform-driver-x86@vger.kernel.org
> >> ---
> >>  include/linux/intel_vsec.h |    7 ++++---
> >>  1 file changed, 4 insertions(+), 3 deletions(-)
> >>
> >> --- linux-next-20251201.orig/include/linux/intel_vsec.h
> >> +++ linux-next-20251201/include/linux/intel_vsec.h
> >> @@ -80,8 +80,8 @@ enum intel_vsec_quirks {
> >>  
> >>  /**
> >>   * struct pmt_callbacks - Callback infrastructure for PMT devices
> >> - * ->read_telem() when specified, called by client driver to access PMT data (instead
> >> - * of direct copy).
> >> + * @read_telem: when specified, called by client driver to access PMT
> >> + * data (instead of direct copy).
> >>   * @pdev:  PCI device reference for the callback's use
> >>   * @guid:  ID of data to acccss
> >>   * @data:  buffer for the data to be copied
> > 
> > Is it correct for kerneldoc to have the rest as @pdev, @guid, etc.,
> > they are parameters to the callback, not members of this struct?
> 
> No, it's not correct. We get away with it in several kernel source files
> because scripts/kernel-doc doesn't check/notice that.
> 
> Would you prefer to have them there but without the leading '@' sign?
> Or completely delete those lines?
> IMO they are useful/informative, so I would rather not delete them.

Can we use some * * formatting trick to them as well as remove the @. I'm 
not sure how kernel doc deals with formatting * * within the parameters 
paragraph but if it works like in return formatting, I guess that would 
seem like the most useful approach.

If it doesn't work, then just remove @, I think.

-- 
 i.

> >> @@ -120,7 +120,7 @@ struct intel_vsec_platform_info {
> >>  };
> >>  
> >>  /**
> >> - * struct intel_sec_device - Auxbus specific device information
> >> + * struct intel_vsec_device - Auxbus specific device information
> >>   * @auxdev:        auxbus device struct for auxbus access
> >>   * @pcidev:        pci device associated with the device
> >>   * @resource:      any resources shared by the parent
> >> @@ -128,6 +128,7 @@ struct intel_vsec_platform_info {
> >>   * @num_resources: number of resources
> >>   * @id:            xarray id
> >>   * @priv_data:     any private data needed
> >> + * @priv_data_size: size of private data area
> >>   * @quirks:        specified quirks
> >>   * @base_addr:     base address of entries (if specified)
> >>   * @cap_id:        the enumerated id of the vsec feature
> >>
> > 
> 
> thanks.
> 

Re: [PATCH] platform/x86/intel/vsec: correct kernel-doc comments

[Randy Dunlap]

On 12/15/25 11:21 AM, Ilpo Järvinen wrote:
> On Mon, 15 Dec 2025, Randy Dunlap wrote:
> 
>> Hi Ilpo,
>>
>> On 12/15/25 6:10 AM, Ilpo Järvinen wrote:
>>> On Sun, 14 Dec 2025, Randy Dunlap wrote:
>>>
>>>> Fix kernel-doc warnings in intel_vsec.h to eliminate all kernel-doc
>>>> warnings:
>>>>
>>>> Warning: include/linux/intel_vsec.h:92 struct member 'read_telem' not
>>>>  described in 'pmt_callbacks'
>>>> Warning: include/linux/intel_vsec.h:146 expecting prototype for struct
>>>>  intel_sec_device.  Prototype was for struct intel_vsec_device instead
>>>> Warning: include/linux/intel_vsec.h:146 struct member 'priv_data_size'
>>>>  not described in 'intel_vsec_device'
>>>>
>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>>> ---
>>>> Cc: David E. Box <david.e.box@linux.intel.com>
>>>> Cc: Hans de Goede <hansg@kernel.org>
>>>> Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
>>>> Cc: platform-driver-x86@vger.kernel.org
>>>> ---
>>>>  include/linux/intel_vsec.h |    7 ++++---
>>>>  1 file changed, 4 insertions(+), 3 deletions(-)
>>>>
>>>> --- linux-next-20251201.orig/include/linux/intel_vsec.h
>>>> +++ linux-next-20251201/include/linux/intel_vsec.h
>>>> @@ -80,8 +80,8 @@ enum intel_vsec_quirks {
>>>>  
>>>>  /**
>>>>   * struct pmt_callbacks - Callback infrastructure for PMT devices
>>>> - * ->read_telem() when specified, called by client driver to access PMT data (instead
>>>> - * of direct copy).
>>>> + * @read_telem: when specified, called by client driver to access PMT
>>>> + * data (instead of direct copy).
>>>>   * @pdev:  PCI device reference for the callback's use
>>>>   * @guid:  ID of data to acccss
>>>>   * @data:  buffer for the data to be copied
>>>
>>> Is it correct for kerneldoc to have the rest as @pdev, @guid, etc.,
>>> they are parameters to the callback, not members of this struct?
>>
>> No, it's not correct. We get away with it in several kernel source files
>> because scripts/kernel-doc doesn't check/notice that.
>>
>> Would you prefer to have them there but without the leading '@' sign?
>> Or completely delete those lines?
>> IMO they are useful/informative, so I would rather not delete them.
> 
> Can we use some * * formatting trick to them as well as remove the @. I'm 
> not sure how kernel doc deals with formatting * * within the parameters 
> paragraph but if it works like in return formatting, I guess that would 
> seem like the most useful approach.
> 
> If it doesn't work, then just remove @, I think.

[testing]

The struct members are not formatted like Returns: formatting.

a. If I just drop the at-sign, the struct member descriptions all run
together, no breaks between them. Not acceptable IMO.

b. If I use "* *" before each struct member, the struct member
descriptions still run together but there is a "*" separator
character between them.

c. If I end each struct member description with a '.' (just one
leading '*'), the struct member descriptions run together but
there is an ending '.' between them.

d. If I use "* @member" for each struct member, kernel-doc seems
to ignore those lines completely. No output is produced for those
lines.

So I think we are down to using "* *" for each struct member or
using "* member: Description." so that there is a separator between
each struct member description. Do you have a preference?

Example for b:

       read_telem  when  specified,  called by client driver to access PMT data
                   (instead of direct copy).  * pdev:  PCI device reference for
                   the callback's use * guid:  ID of data  to  acccss  *  data:
                   buffer  for  the  data to be copied * off:   offset into the
                   requested buffer * count: size of buffer

Example for c:

       read_telem  when  specified,  called by client driver to access PMT data
                   (instead of direct copy).  pdev:  PCI device  reference  for
                   the  callback's  use.   guid:   ID of data to acccss.  data:
                   Buffer for the data to be copied.  off:    Offset  into  the
                   requested buffer.  count: Size of buffer.

Or we could just drop the patch if you don't care for any of these.

thanks.
-- 
~Randy

Re: [PATCH] platform/x86/intel/vsec: correct kernel-doc comments

[Ilpo Järvinen]

[-- Attachment #1: Type: text/plain, Size: 4649 bytes --]

On Mon, 15 Dec 2025, Randy Dunlap wrote:
> On 12/15/25 11:21 AM, Ilpo Järvinen wrote:
> > On Mon, 15 Dec 2025, Randy Dunlap wrote:
> > 
> >> Hi Ilpo,
> >>
> >> On 12/15/25 6:10 AM, Ilpo Järvinen wrote:
> >>> On Sun, 14 Dec 2025, Randy Dunlap wrote:
> >>>
> >>>> Fix kernel-doc warnings in intel_vsec.h to eliminate all kernel-doc
> >>>> warnings:
> >>>>
> >>>> Warning: include/linux/intel_vsec.h:92 struct member 'read_telem' not
> >>>>  described in 'pmt_callbacks'
> >>>> Warning: include/linux/intel_vsec.h:146 expecting prototype for struct
> >>>>  intel_sec_device.  Prototype was for struct intel_vsec_device instead
> >>>> Warning: include/linux/intel_vsec.h:146 struct member 'priv_data_size'
> >>>>  not described in 'intel_vsec_device'
> >>>>
> >>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> >>>> ---
> >>>> Cc: David E. Box <david.e.box@linux.intel.com>
> >>>> Cc: Hans de Goede <hansg@kernel.org>
> >>>> Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
> >>>> Cc: platform-driver-x86@vger.kernel.org
> >>>> ---
> >>>>  include/linux/intel_vsec.h |    7 ++++---
> >>>>  1 file changed, 4 insertions(+), 3 deletions(-)
> >>>>
> >>>> --- linux-next-20251201.orig/include/linux/intel_vsec.h
> >>>> +++ linux-next-20251201/include/linux/intel_vsec.h
> >>>> @@ -80,8 +80,8 @@ enum intel_vsec_quirks {
> >>>>  
> >>>>  /**
> >>>>   * struct pmt_callbacks - Callback infrastructure for PMT devices
> >>>> - * ->read_telem() when specified, called by client driver to access PMT data (instead
> >>>> - * of direct copy).
> >>>> + * @read_telem: when specified, called by client driver to access PMT
> >>>> + * data (instead of direct copy).
> >>>>   * @pdev:  PCI device reference for the callback's use
> >>>>   * @guid:  ID of data to acccss
> >>>>   * @data:  buffer for the data to be copied
> >>>
> >>> Is it correct for kerneldoc to have the rest as @pdev, @guid, etc.,
> >>> they are parameters to the callback, not members of this struct?
> >>
> >> No, it's not correct. We get away with it in several kernel source files
> >> because scripts/kernel-doc doesn't check/notice that.
> >>
> >> Would you prefer to have them there but without the leading '@' sign?
> >> Or completely delete those lines?
> >> IMO they are useful/informative, so I would rather not delete them.
> > 
> > Can we use some * * formatting trick to them as well as remove the @. I'm 
> > not sure how kernel doc deals with formatting * * within the parameters 
> > paragraph but if it works like in return formatting, I guess that would 
> > seem like the most useful approach.
> > 
> > If it doesn't work, then just remove @, I think.
> 
> [testing]
> 
> The struct members are not formatted like Returns: formatting.

Thanks for testing. Lets go with example b, that looks most readable out 
of the options.

> a. If I just drop the at-sign, the struct member descriptions all run
> together, no breaks between them. Not acceptable IMO.
> 
> b. If I use "* *" before each struct member, the struct member
> descriptions still run together but there is a "*" separator
> character between them.
> 
> c. If I end each struct member description with a '.' (just one
> leading '*'), the struct member descriptions run together but
> there is an ending '.' between them.
> 
> d. If I use "* @member" for each struct member, kernel-doc seems
> to ignore those lines completely. No output is produced for those
> lines.
> 
> So I think we are down to using "* *" for each struct member or
> using "* member: Description." so that there is a separator between
> each struct member description. Do you have a preference?
> 
> Example for b:
> 
>        read_telem  when  specified,  called by client driver to access PMT data
>                    (instead of direct copy).  * pdev:  PCI device reference for
>                    the callback's use * guid:  ID of data  to  acccss  *  data:
>                    buffer  for  the  data to be copied * off:   offset into the
>                    requested buffer * count: size of buffer
> 
> Example for c:
> 
>        read_telem  when  specified,  called by client driver to access PMT data
>                    (instead of direct copy).  pdev:  PCI device  reference  for
>                    the  callback's  use.   guid:   ID of data to acccss.  data:
>                    Buffer for the data to be copied.  off:    Offset  into  the
>                    requested buffer.  count: Size of buffer.
> 
> Or we could just drop the patch if you don't care for any of these.
> 
> thanks.
> 

-- 
 i.