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

["Ilpo Järvinen" <ilpo.jarvinen@linux.intel.com>]

[-- 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.
>