[PATCH] firmware: raspberrypi: Add missing kernel-doc Return sections

[Tomasz Unger]

scripts/kernel-doc -Wall reports four functions in this file with no
description of their return value:

  rpi_firmware_property_list()
  rpi_firmware_property()
  rpi_firmware_get()
  devm_rpi_firmware_get()

Add a "Return:" section to the first two. The last two already describe
the return value, but in a free-form "Returns NULL is ..." sentence that
kernel-doc does not recognize. Convert it to a "Return:" section and fix
the "is" -> "if" typo while at it. For devm_rpi_firmware_get() also
mention that NULL is returned when registering the devm release action
fails.

No functional change.

Signed-off-by: Tomasz Unger <tomasz.unger@xxxxxxxx>
---
 drivers/firmware/raspberrypi.c | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/drivers/firmware/raspberrypi.c b/drivers/firmware/raspberrypi.c
index 443459c8c90f..61c0e1f7b3e3 100644
--- a/drivers/firmware/raspberrypi.c
+++ b/drivers/firmware/raspberrypi.c
@@ -85,6 +85,8 @@ rpi_firmware_transaction(struct rpi_firmware *fw, u32 chan, u32 data)
  * don't need to be supplied, just the actual tags for your operation.
  * See struct rpi_firmware_property_tag_header for the per-tag
  * structure.
+ *
+ * Return: 0 on success, or a negative error code on failure.
  */
 int rpi_firmware_property_list(struct rpi_firmware *fw,
 			       void *data, size_t tag_size)
@@ -148,6 +150,8 @@ EXPORT_SYMBOL_GPL(rpi_firmware_property_list);
  * This is a convenience wrapper around
  * rpi_firmware_property_list() to avoid some of the
  * boilerplate in property calls.
+ *
+ * Return: 0 on success, or a negative error code on failure.
  */
 int rpi_firmware_property(struct rpi_firmware *fw,
 			  u32 tag, void *tag_data, size_t buf_size)
@@ -373,7 +377,8 @@ EXPORT_SYMBOL_GPL(rpi_firmware_find_node);
  *
  * The reference to rpi_firmware has to be released with rpi_firmware_put().
  *
- * Returns NULL is the firmware device is not ready.
+ * Return: pointer to the rpi_firmware structure, or NULL if the firmware
+ * device is not ready.
  */
 struct rpi_firmware *rpi_firmware_get(struct device_node *firmware_node)
 {
@@ -405,7 +410,8 @@ EXPORT_SYMBOL_GPL(rpi_firmware_get);
  * @dev:              The firmware device structure
  * @firmware_node:    Pointer to the firmware Device Tree node.
  *
- * Returns NULL is the firmware device is not ready.
+ * Return: pointer to the rpi_firmware structure, or NULL if the firmware
+ * device is not ready or the release action could not be registered.
  */
 struct rpi_firmware *devm_rpi_firmware_get(struct device *dev,
 					   struct device_node *firmware_node)

---
base-commit: 6628e7d4c6b25c8d18f1345e3a20d21829aae7e4
change-id: 20261110-rpi-fw-kdoc-return-d171b914f4ca

Best regards,
--  
Tomasz Unger <tomasz.unger@xxxxxxxx>