Skip to contentSkip to conversation

device property: Fix documentation for *_match_string() APIs

PATCH In review Andy Shevchenko 3 participants 7 messages Oct 6, 2022 – Oct 26, 2022

Subsystems (3)
lore
Share & tools
lore

Andy Shevchenko

author reviewer
#0 lore raw

PATCH 1/1 device property: Fix documentation for *_match_string() APIs

The returned value on success is an index of the matching string, starting from 0. Reflect this in the documentation.

Fixes 3f5c8d318785 ("device property: Add fwnode_property_match_string()")
---
 drivers/base/property.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/base/property.c +2 -2
index 617007a25783..bfed224c5724 100644
@@ -236,7 +236,7 @@ EXPORT_SYMBOL_GPL(device_property_read_string);
  * Find a given string in a string array and if it is found return the
  * index back.
  *
- * Return: %0 if the property was found (success),
+ * Return: index, starting from %0, if the property was found (success),
  *	   %-EINVAL if given arguments are not valid,
  *	   %-ENODATA if the property does not have a value,
  *	   %-EPROTO if the property is not an array of strings,
@@ -457,7 +457,7 @@ EXPORT_SYMBOL_GPL(fwnode_property_read_string);
  * Find a given string in a string array and if it is found return the
  * index back.
  *
- * Return: %0 if the property was found (success),
+ * Return: index, starting from %0, if the property was found (success),
  *	   %-EINVAL if given arguments are not valid,
  *	   %-ENODATA if the property does not have a value,
  *	   %-EPROTO if the property is not an array of strings,
Signature · 1 line
2.35.1
reviewer Reviewed-by on v1 1/1
#1 lore raw

Hi Andy,

Quoted 14 lines · Andy Shevchenko

The returned value on success is an index of the matching string, starting from 0. Reflect this in the documentation.

Fixes 3f5c8d318785 ("device property: Add fwnode_property_match_string()")
---
 drivers/base/property.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/base/property.c +0 -0
index 617007a25783..bfed224c5724 100644

drivers/base/property.c EXPORT_SYMBOL_GPL(device_property_read_string); · line 242

Quoted 8 lines
drivers/base/property.c +1 -1
@@ -236,7 +236,7 @@ EXPORT_SYMBOL_GPL(device_property_read_string);
  * Find a given string in a string array and if it is found return the
  * index back.
  *
- * Return: %0 if the property was found (success),
+ * Return: index, starting from %0, if the property was found (success),
  *	   %-EINVAL if given arguments are not valid,
  *	   %-ENODATA if the property does not have a value,
  *	   %-EPROTO if the property is not an array of strings,

There are other error codes that can be returned such as -ENOMEM or what else may be returned by fwnode_property_read_string_array().

I might just refer to fwnode_property_read_string_array() and document here those specific to these functions.

Just FYI... I guess this could be a separate patch, too.

Quoted 9 lines
drivers/base/property.c +1 -1
@@ -457,7 +457,7 @@ EXPORT_SYMBOL_GPL(fwnode_property_read_string);
  * Find a given string in a string array and if it is found return the
  * index back.
  *
- * Return: %0 if the property was found (success),
+ * Return: index, starting from %0, if the property was found (success),
  *	   %-EINVAL if given arguments are not valid,
  *	   %-ENODATA if the property does not have a value,
  *	   %-EPROTO if the property is not an array of strings,
Signature · 3 lines
Kind regards,

Sakari Ailus
author reviewer
#2 lore raw
Quoted 5 lines · Sakari Ailus
Quoted 4 lines · Andy Shevchenko

The returned value on success is an index of the matching string, starting from 0. Reflect this in the documentation.

Fixes 3f5c8d318785 ("device property: Add fwnode_property_match_string()")

...

Quoted 6 lines
Quoted 5 lines

- * Return: %0 if the property was found (success),
+ * Return: index, starting from %0, if the property was found (success),

  *	   %-EINVAL if given arguments are not valid,
  *	   %-ENODATA if the property does not have a value,
  *	   %-EPROTO if the property is not an array of strings,
Quoted 7 lines

There are other error codes that can be returned such as -ENOMEM or what else may be returned by fwnode_property_read_string_array().

I might just refer to fwnode_property_read_string_array() and document here those specific to these functions.

Just FYI... I guess this could be a separate patch, too.

Right, I think we would rather do an incremental change since that will be more intrusive and would not be exactly the fix (improvement?).

Quoted 1 line

Thanks!

Signature · 2 lines
With Best Regards,
Andy Shevchenko
reviewer
#3 lore raw
Quoted 18 lines · Andy Shevchenko
Quoted 5 lines · Sakari Ailus
Quoted 4 lines · Andy Shevchenko

The returned value on success is an index of the matching string, starting from 0. Reflect this in the documentation.

Fixes 3f5c8d318785 ("device property: Add fwnode_property_match_string()")

...

Quoted 9 lines
Quoted 5 lines

- * Return: %0 if the property was found (success),
+ * Return: index, starting from %0, if the property was found (success),

  *	   %-EINVAL if given arguments are not valid,
  *	   %-ENODATA if the property does not have a value,
  *	   %-EPROTO if the property is not an array of strings,

There are other error codes that can be returned such as -ENOMEM or what else may be returned by fwnode_property_read_string_array().

Quoted 7 lines
Quoted 4 lines

I might just refer to fwnode_property_read_string_array() and document here those specific to these functions.

Just FYI... I guess this could be a separate patch, too.

Right, I think we would rather do an incremental change since that will be more intrusive and would not be exactly the fix (improvement?).

It's a fix in documentation. It's perhaps unlikely a bug would have been introduced because of what was missing.

Quoted 4 lines
Quoted 2 lines

Thanks!

You're welcome!

Signature · 1 line
Sakari Ailus
author reviewer
#4 lore raw
In reply to Andy Shevchenko
Quoted 5 lines · Andy Shevchenko

The returned value on success is an index of the matching string, starting from 0. Reflect this in the documentation.

Fixes 3f5c8d318785 ("device property: Add fwnode_property_match_string()")

Is this gone through the cracks?

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#5 lore raw
Quoted 9 lines · Andy Shevchenko
Quoted 5 lines · Andy Shevchenko

The returned value on success is an index of the matching string, starting from 0. Reflect this in the documentation.

Fixes 3f5c8d318785 ("device property: Add fwnode_property_match_string()")

Is this gone through the cracks?

No, it is not. I've just applied it for 6.1-rc3.

Thanks!

author reviewer
#6 lore raw
Quoted 6 lines · Rafael J. Wysocki
Quoted 4 lines · Andy Shevchenko
Quoted 3 lines · Andy Shevchenko

The returned value on success is an index of the matching string, starting from 0. Reflect this in the documentation.

Quoted 6 lines
Quoted 4 lines
Quoted 2 lines
Fixes 3f5c8d318785 ("device property: Add fwnode_property_match_string()")

Is this gone through the cracks?

No, it is not. I've just applied it for 6.1-rc3.

Thank you, Rafael!

Signature · 2 lines
With Best Regards,
Andy Shevchenko