[PATCH] device property: add missing kernel-doc for property_entry

[PATCH] device property: add missing kernel-doc for property_entry

[Randy Dunlap]

Add kernel-doc for the missing fields in union value:

Warning: include/linux/property.h:406 struct member 'u8_data' not
 described in 'property_entry'
Warning: include/linux/property.h:406 struct member 'u16_data' not
 described in 'property_entry'
Warning: include/linux/property.h:406 struct member 'u32_data' not
 described in 'property_entry'
Warning: include/linux/property.h:406 struct member 'u64_data' not
 described in 'property_entry'
Warning: include/linux/property.h:406 struct member 'str' not described
 in 'property_entry'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Cc: Daniel Scally <djrscally@gmail.com>
Cc: Heikki Krogerus <heikki.krogerus@linux.intel.com>
Cc: Sakari Ailus <sakari.ailus@linux.intel.com>
Cc: linux-acpi@vger.kernel.org
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: "Rafael J. Wysocki" <rafael@kernel.org>
Cc: Danilo Krummrich <dakr@kernel.org>
Cc: driver-core@lists.linux.dev

 include/linux/property.h |    5 +++++
 1 file changed, 5 insertions(+)

--- linux-next-20260717.orig/include/linux/property.h
+++ linux-next-20260717/include/linux/property.h
@@ -388,6 +388,11 @@ struct software_node_ref_args {
  * @type: Type of the data in unions.
  * @pointer: Pointer to the property when it is not stored inline.
  * @value: Value of the property when it is stored inline.
+ * @u8_data: @value as an array of u8 numbers
+ * @u16_data: @value as an array of u16 numbers
+ * @u32_data: @value as an array of u32 numbers
+ * @u64_data: @value as an array of u64 numbers
+ * @str: @value as an array of char pointers
  */
 struct property_entry {
 	const char *name;

Re: [PATCH] device property: add missing kernel-doc for property_entry

[Sakari Ailus]

On Sun, Jul 19, 2026 at 03:36:40PM -0700, Randy Dunlap wrote:
> Add kernel-doc for the missing fields in union value:
> 
> Warning: include/linux/property.h:406 struct member 'u8_data' not
>  described in 'property_entry'
> Warning: include/linux/property.h:406 struct member 'u16_data' not
>  described in 'property_entry'
> Warning: include/linux/property.h:406 struct member 'u32_data' not
>  described in 'property_entry'
> Warning: include/linux/property.h:406 struct member 'u64_data' not
>  described in 'property_entry'
> Warning: include/linux/property.h:406 struct member 'str' not described
>  in 'property_entry'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus

Re: [PATCH] device property: add missing kernel-doc for property_entry

[Andy Shevchenko]

On Sun, Jul 19, 2026 at 03:36:40PM -0700, Randy Dunlap wrote:
> Add kernel-doc for the missing fields in union value:
> 
> Warning: include/linux/property.h:406 struct member 'u8_data' not
>  described in 'property_entry'
> Warning: include/linux/property.h:406 struct member 'u16_data' not
>  described in 'property_entry'
> Warning: include/linux/property.h:406 struct member 'u32_data' not
>  described in 'property_entry'
> Warning: include/linux/property.h:406 struct member 'u64_data' not
>  described in 'property_entry'
> Warning: include/linux/property.h:406 struct member 'str' not described
>  in 'property_entry'

...

>   * @pointer: Pointer to the property when it is not stored inline.
>   * @value: Value of the property when it is stored inline.

> + * @u8_data: @value as an array of u8 numbers
> + * @u16_data: @value as an array of u16 numbers
> + * @u32_data: @value as an array of u32 numbers
> + * @u64_data: @value as an array of u64 numbers
> + * @str: @value as an array of char pointers

I think the proper fix is to add

	/* private: internal representation of @value */

>   */

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH] device property: add missing kernel-doc for property_entry

[Randy Dunlap]

On 7/20/26 4:51 AM, Andy Shevchenko wrote:
> On Sun, Jul 19, 2026 at 03:36:40PM -0700, Randy Dunlap wrote:
>> Add kernel-doc for the missing fields in union value:
>>
>> Warning: include/linux/property.h:406 struct member 'u8_data' not
>>  described in 'property_entry'
>> Warning: include/linux/property.h:406 struct member 'u16_data' not
>>  described in 'property_entry'
>> Warning: include/linux/property.h:406 struct member 'u32_data' not
>>  described in 'property_entry'
>> Warning: include/linux/property.h:406 struct member 'u64_data' not
>>  described in 'property_entry'
>> Warning: include/linux/property.h:406 struct member 'str' not described
>>  in 'property_entry'
> 
> ...
> 
>>   * @pointer: Pointer to the property when it is not stored inline.
>>   * @value: Value of the property when it is stored inline.
> 
>> + * @u8_data: @value as an array of u8 numbers
>> + * @u16_data: @value as an array of u16 numbers
>> + * @u32_data: @value as an array of u32 numbers
>> + * @u64_data: @value as an array of u64 numbers
>> + * @str: @value as an array of char pointers
> 
> I think the proper fix is to add
> 
> 	/* private: internal representation of @value */
> 
>>   */

OK :)

-- 
~Randy

Re: [PATCH] device property: add missing kernel-doc for property_entry

[Andy Shevchenko]

On Mon, Jul 20, 2026 at 08:30:59AM -0700, Randy Dunlap wrote:
> On 7/20/26 4:51 AM, Andy Shevchenko wrote:
> > On Sun, Jul 19, 2026 at 03:36:40PM -0700, Randy Dunlap wrote:
> >> Add kernel-doc for the missing fields in union value:
> >>
> >> Warning: include/linux/property.h:406 struct member 'u8_data' not
> >>  described in 'property_entry'
> >> Warning: include/linux/property.h:406 struct member 'u16_data' not
> >>  described in 'property_entry'
> >> Warning: include/linux/property.h:406 struct member 'u32_data' not
> >>  described in 'property_entry'
> >> Warning: include/linux/property.h:406 struct member 'u64_data' not
> >>  described in 'property_entry'
> >> Warning: include/linux/property.h:406 struct member 'str' not described
> >>  in 'property_entry'

...

> >>   * @pointer: Pointer to the property when it is not stored inline.
> >>   * @value: Value of the property when it is stored inline.
> > 
> >> + * @u8_data: @value as an array of u8 numbers
> >> + * @u16_data: @value as an array of u16 numbers
> >> + * @u32_data: @value as an array of u32 numbers
> >> + * @u64_data: @value as an array of u64 numbers
> >> + * @str: @value as an array of char pointers
> > 
> > I think the proper fix is to add
> > 
> > 	/* private: internal representation of @value */
> > 
> >>   */
> 
> OK :)

FWIW, while checking this, I found that kernel-doc seems missing the case as
above, so the proper handling via @value.u8_data: and so on doesn't work
because it's wrapped in anonymous union, and there is no such examples in the
documentation.

In any case, those fields are indeed private (or in C++ terms more like
"protected"). Hence my above suggestion is the way to go.

-- 
With Best Regards,
Andy Shevchenko