[PATCH] iio: tsl2772: fix all kernel-doc warnings

[PATCH] iio: tsl2772: fix all kernel-doc warnings

[Randy Dunlap]

Use the correct kernel-doc notation for struct members to eliminate
kernel-doc warnings:

Warning: include/linux/platform_data/tsl2772.h:88 struct member
 'prox_diode' not described in 'tsl2772_settings'
Warning: include/linux/platform_data/tsl2772.h:88 struct member
 'prox_power' not described in 'tsl2772_settings'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Jonathan Cameron <jic23@kernel.org>
Cc: David Lechner <dlechner@baylibre.com>
Cc: Nuno Sá <nuno.sa@analog.com>
Cc: Andy Shevchenko <andy@kernel.org>
Cc: linux-iio@vger.kernel.org

 include/linux/platform_data/tsl2772.h |    4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

--- linux-next-20260225.orig/include/linux/platform_data/tsl2772.h
+++ linux-next-20260225/include/linux/platform_data/tsl2772.h
@@ -61,9 +61,9 @@ struct tsl2772_lux {
  *  @prox_pulse_count:      Number if proximity emitter pulses.
  *  @prox_max_samples_cal:  The number of samples that are taken when performing
  *                          a proximity calibration.
- *  @prox_diode             Which diode(s) to use for driving the external
+ *  @prox_diode:            Which diode(s) to use for driving the external
  *                          LED(s) for proximity sensing.
- *  @prox_power             The amount of power to use for the external LED(s).
+ *  @prox_power:            The amount of power to use for the external LED(s).
  */
 struct tsl2772_settings {
 	int als_time;

Re: [PATCH] iio: tsl2772: fix all kernel-doc warnings

[Andy Shevchenko]

On Wed, Feb 25, 2026 at 09:12:57PM -0800, Randy Dunlap wrote:
> Use the correct kernel-doc notation for struct members to eliminate
> kernel-doc warnings:
> 
> Warning: include/linux/platform_data/tsl2772.h:88 struct member
>  'prox_diode' not described in 'tsl2772_settings'
> Warning: include/linux/platform_data/tsl2772.h:88 struct member
>  'prox_power' not described in 'tsl2772_settings'

Hmm... I do not see any of the user of this header file.
Have you checked if these values are even used?
Perhaps we can simply kill all this?

But if Jonathan wants to take this as a quick fix to make less
warnings appear effective immediately I'm fine with the change
Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH] iio: tsl2772: fix all kernel-doc warnings

[Randy Dunlap]

On 2/26/26 12:04 AM, Andy Shevchenko wrote:
> On Wed, Feb 25, 2026 at 09:12:57PM -0800, Randy Dunlap wrote:
>> Use the correct kernel-doc notation for struct members to eliminate
>> kernel-doc warnings:
>>
>> Warning: include/linux/platform_data/tsl2772.h:88 struct member
>>  'prox_diode' not described in 'tsl2772_settings'
>> Warning: include/linux/platform_data/tsl2772.h:88 struct member
>>  'prox_power' not described in 'tsl2772_settings'
> 
> Hmm... I do not see any of the user of this header file.
> Have you checked if these values are even used?
> Perhaps we can simply kill all this?

They are used in drivers/iio/light/tsl2772.c.

> But if Jonathan wants to take this as a quick fix to make less
> warnings appear effective immediately I'm fine with the change
> Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>
> 
Thanks.
-- 
~Randy

Re: [PATCH] iio: tsl2772: fix all kernel-doc warnings

[Andy Shevchenko]

On Thu, Feb 26, 2026 at 11:14:05AM -0800, Randy Dunlap wrote:
> On 2/26/26 12:04 AM, Andy Shevchenko wrote:
> > On Wed, Feb 25, 2026 at 09:12:57PM -0800, Randy Dunlap wrote:
> >> Use the correct kernel-doc notation for struct members to eliminate
> >> kernel-doc warnings:
> >>
> >> Warning: include/linux/platform_data/tsl2772.h:88 struct member
> >>  'prox_diode' not described in 'tsl2772_settings'
> >> Warning: include/linux/platform_data/tsl2772.h:88 struct member
> >>  'prox_power' not described in 'tsl2772_settings'
> > 
> > Hmm... I do not see any of the user of this header file.
> > Have you checked if these values are even used?
> > Perhaps we can simply kill all this?
> 
> They are used in drivers/iio/light/tsl2772.c.

It's the same driver. So it's *not* a user of the platform data.

Under 'kill' I meant the following:
- inline the content of the file to the c-file
- recheck the c-file for the unused fields and drop them for good

Alternatively converting c-file to use device properties instead
of platform data.

We have done many times in the past such transformations in other
drivers.

> > But if Jonathan wants to take this as a quick fix to make less
> > warnings appear effective immediately I'm fine with the change
> > Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH] iio: tsl2772: fix all kernel-doc warnings

[Randy Dunlap]

Hi Andy,

On 2/26/26 12:29 PM, Andy Shevchenko wrote:
> On Thu, Feb 26, 2026 at 11:14:05AM -0800, Randy Dunlap wrote:
>> On 2/26/26 12:04 AM, Andy Shevchenko wrote:
>>> On Wed, Feb 25, 2026 at 09:12:57PM -0800, Randy Dunlap wrote:
>>>> Use the correct kernel-doc notation for struct members to eliminate
>>>> kernel-doc warnings:
>>>>
>>>> Warning: include/linux/platform_data/tsl2772.h:88 struct member
>>>>  'prox_diode' not described in 'tsl2772_settings'
>>>> Warning: include/linux/platform_data/tsl2772.h:88 struct member
>>>>  'prox_power' not described in 'tsl2772_settings'
>>>
>>> Hmm... I do not see any of the user of this header file.
>>> Have you checked if these values are even used?
>>> Perhaps we can simply kill all this?

AFAICT all macros and structs and struct members from that header file are used
in tsl2772.c.

>> They are used in drivers/iio/light/tsl2772.c.
> 
> It's the same driver. So it's *not* a user of the platform data.
> 
> Under 'kill' I meant the following:
> - inline the content of the file to the c-file

Would that be "violating" this commit?
commit 436d42c61c3e
Author: Arnd Bergmann <arnd@arndb.de>
Date:   Fri Aug 24 15:22:12 2012 +0200

    ARM: samsung: move platform_data definitions
    
    Platform data for device drivers should be defined in
    include/linux/platform_data/*.h, not in the architecture
    and platform specific directories.

> - recheck the c-file for the unused fields and drop them for good

All used AFAICT.

> Alternatively converting c-file to use device properties instead
> of platform data.

That's your area, I guess.

> We have done many times in the past such transformations in other
> drivers.
> 
>>> But if Jonathan wants to take this as a quick fix to make less
>>> warnings appear effective immediately I'm fine with the change
>>> Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>
> 
thanks.
-- 
~Randy

Re: [PATCH] iio: tsl2772: fix all kernel-doc warnings

[Jonathan Cameron]

On Thu, 26 Feb 2026 14:25:12 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> Hi Andy,
> 
> On 2/26/26 12:29 PM, Andy Shevchenko wrote:
> > On Thu, Feb 26, 2026 at 11:14:05AM -0800, Randy Dunlap wrote:  
> >> On 2/26/26 12:04 AM, Andy Shevchenko wrote:  
> >>> On Wed, Feb 25, 2026 at 09:12:57PM -0800, Randy Dunlap wrote:  
> >>>> Use the correct kernel-doc notation for struct members to eliminate
> >>>> kernel-doc warnings:
> >>>>
> >>>> Warning: include/linux/platform_data/tsl2772.h:88 struct member
> >>>>  'prox_diode' not described in 'tsl2772_settings'
> >>>> Warning: include/linux/platform_data/tsl2772.h:88 struct member
> >>>>  'prox_power' not described in 'tsl2772_settings'  
> >>>
> >>> Hmm... I do not see any of the user of this header file.
> >>> Have you checked if these values are even used?
> >>> Perhaps we can simply kill all this?  
> 
> AFAICT all macros and structs and struct members from that header file are used
> in tsl2772.c.
> 
> >> They are used in drivers/iio/light/tsl2772.c.  
> > 
> > It's the same driver. So it's *not* a user of the platform data.
> > 
> > Under 'kill' I meant the following:
> > - inline the content of the file to the c-file  
> 
> Would that be "violating" this commit?

I think the proposal is to remove platform data support entirely from
this driver on basis we have no upstream users.

There are defaults in driver for the stuff that can still come from
platform data.  Note there is generic property support for a bunch
of other stuff (i assume for DT).

So I'd be fine with a patch that removes this header and the use
of platform data in the driver. Easiest path to that is as Andy described
in putting the defs in the c file, plus only using the driver defaults
(so no more 'real' platform data).

Jonathan

> commit 436d42c61c3e
> Author: Arnd Bergmann <arnd@arndb.de>
> Date:   Fri Aug 24 15:22:12 2012 +0200
> 
>     ARM: samsung: move platform_data definitions
>     
>     Platform data for device drivers should be defined in
>     include/linux/platform_data/*.h, not in the architecture
>     and platform specific directories.
> 
> > - recheck the c-file for the unused fields and drop them for good  
> 
> All used AFAICT.
> 
> > Alternatively converting c-file to use device properties instead
> > of platform data.  
> 
> That's your area, I guess.
> 
> > We have done many times in the past such transformations in other
> > drivers.
> >   
> >>> But if Jonathan wants to take this as a quick fix to make less
> >>> warnings appear effective immediately I'm fine with the change
> >>> Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>  
> >   
> thanks.

Re: [PATCH] iio: tsl2772: fix all kernel-doc warnings

[Jonathan Cameron]

On Thu, 26 Feb 2026 10:04:53 +0200
Andy Shevchenko <andriy.shevchenko@intel.com> wrote:

> On Wed, Feb 25, 2026 at 09:12:57PM -0800, Randy Dunlap wrote:
> > Use the correct kernel-doc notation for struct members to eliminate
> > kernel-doc warnings:
> > 
> > Warning: include/linux/platform_data/tsl2772.h:88 struct member
> >  'prox_diode' not described in 'tsl2772_settings'
> > Warning: include/linux/platform_data/tsl2772.h:88 struct member
> >  'prox_power' not described in 'tsl2772_settings'  
> 
> Hmm... I do not see any of the user of this header file.
> Have you checked if these values are even used?
> Perhaps we can simply kill all this?
> 
> But if Jonathan wants to take this as a quick fix to make less
> warnings appear effective immediately I'm fine with the change
> Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>
I've picked it up because even if we do rip out platform data support
it's likely the structures will remain and then we'll want them
to have correctly formatted docs

So applied

Thanks,

Jonathan

>