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: <272b0029-66ce-40b3-8f87-a24eee06f844@infradead.org>
Date: Mon, 15 Dec 2025 11:59:43 -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



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