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

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

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