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

[PATCH v2] 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'

In struct pmt_callbacks, correct the kernel-doc for @read_telem.
kernel-doc doesn't support documenting callback function parameters,
so drop the '@' signs on those and use "* *" to make them somewhat
readable in the produced documentation output.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
v2: make changes to the callback fn parameters as requested by Ilpo.

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 |   17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

--- linux-next-20251210.orig/include/linux/intel_vsec.h
+++ linux-next-20251210/include/linux/intel_vsec.h
@@ -80,13 +80,13 @@ 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).
- * @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
+ * @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
  */
 struct pmt_callbacks {
 	int (*read_telem)(struct pci_dev *pdev, u32 guid, u64 *data, loff_t off, u32 count);
@@ -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 v2] platform/x86/intel/vsec: correct kernel-doc comments

[Ilpo Järvinen]

On Mon, 15 Dec 2025 22:38:00 -0800, 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'
> 
> [...]


Thank you for your contribution, it has been applied to my local
review-ilpo-fixes branch. Note it will show up in the public
platform-drivers-x86/review-ilpo-fixes branch only once I've pushed my
local branch there, which might take a while.

The list of commits applied:
[1/1] platform/x86/intel/vsec: correct kernel-doc comments
      commit: 20e20b147cf7cb6780a5b95da2a0e37c52cd1015

--
 i.