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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <c6198da4-c596-4ed7-b4a4-f43046cca34c@infradead.org>
Date: Mon, 15 Dec 2025 10:47:27 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
Cc: LKML <linux-kernel@...r.kernel.org>,
 "David E. Box" <david.e.box@...ux.intel.com>,
 Hans de Goede <hansg@...nel.org>, platform-driver-x86@...r.kernel.org
Subject: Re: [PATCH] platform/x86/intel/vsec: correct kernel-doc comments

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@...radead.org>
>> ---
>> Cc: David E. Box <david.e.box@...ux.intel.com>
>> Cc: Hans de Goede <hansg@...nel.org>
>> Cc: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
>> Cc: platform-driver-x86@...r.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