net: mdio: eliminate kdoc warnings in mdio_device.c and mdio_bus.c

Fix all warnings reported by scripts/kernel-doc in
mdio_device.c and mdio_bus.c

Signed-off-by: Buday Csaba <buday.csaba@prolan.hu>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Link: https://patch.msgid.link/7ef7b80669da2b899d38afdb6c45e122229c3d8c.1763968667.git.buday.csaba@prolan.hu
Signed-off-by: Jakub Kicinski <kuba@kernel.org>

2 files changed, 55 insertions, 7 deletions

diff --git a/drivers/net/phy/mdio_bus.c b/drivers/net/phy/mdio_bus.c
index ef041ad66852..afdf1ad6c0e6 100644
--- a/drivers/net/phy/mdio_bus.c
+++ b/drivers/net/phy/mdio_bus.c
@@ -339,7 +339,7 @@ EXPORT_SYMBOL_GPL(mdio_bus_class);
  * mdio_find_bus - Given the name of a mdiobus, find the mii_bus.
  * @mdio_name: The name of a mdiobus.
  *
- * Returns a reference to the mii_bus, or NULL if none found.  The
+ * Return: a reference to the mii_bus, or NULL if none found. The
  * embedded struct device will have its reference count incremented,
  * and this must be put_deviced'ed once the bus is finished with.
  */
@@ -357,7 +357,7 @@ EXPORT_SYMBOL(mdio_find_bus);
  * of_mdio_find_bus - Given an mii_bus node, find the mii_bus.
  * @mdio_bus_np: Pointer to the mii_bus.
  *
- * Returns a reference to the mii_bus, or NULL if none found.  The
+ * Return: a reference to the mii_bus, or NULL if none found. The
  * embedded struct device will have its reference count incremented,
  * and this must be put once the bus is finished with.
  *
@@ -405,6 +405,8 @@ out:
  * @addr: the phy address
  * @regnum: register number to read
  *
+ * Return: The register value if successful, negative error code on failure
+ *
  * Read a MDIO bus register. Caller must hold the mdio bus lock.
  *
  * NOTE: MUST NOT be called from interrupt context.
@@ -437,6 +439,8 @@ EXPORT_SYMBOL(__mdiobus_read);
  * @regnum: register number to write
  * @val: value to write to @regnum
  *
+ * Return: Zero if successful, negative error code on failure
+ *
  * Write a MDIO bus register. Caller must hold the mdio bus lock.
  *
  * NOTE: MUST NOT be called from interrupt context.
@@ -470,8 +474,11 @@ EXPORT_SYMBOL(__mdiobus_write);
  * @mask: bit mask of bits to clear
  * @set: bit mask of bits to set
  *
+ * Return: 1 if the register was modified, 0 if no change was needed,
+ *	   negative on any error condition
+ *
  * Read, modify, and if any change, write the register value back to the
- * device. Any error returns a negative number.
+ * device.
  *
  * NOTE: MUST NOT be called from interrupt context.
  */
@@ -501,6 +508,8 @@ EXPORT_SYMBOL_GPL(__mdiobus_modify_changed);
  * @devad: device address to read
  * @regnum: register number to read
  *
+ * Return: The register value if successful, negative error code on failure
+ *
  * Read a MDIO bus register. Caller must hold the mdio bus lock.
  *
  * NOTE: MUST NOT be called from interrupt context.
@@ -534,6 +543,8 @@ EXPORT_SYMBOL(__mdiobus_c45_read);
  * @regnum: register number to write
  * @val: value to write to @regnum
  *
+ * Return: Zero if successful, negative error code on failure
+ *
  * Write a MDIO bus register. Caller must hold the mdio bus lock.
  *
  * NOTE: MUST NOT be called from interrupt context.
@@ -569,6 +580,9 @@ EXPORT_SYMBOL(__mdiobus_c45_write);
  * @mask: bit mask of bits to clear
  * @set: bit mask of bits to set
  *
+ * Return: 1 if the register was modified, 0 if no change was needed,
+ *	   negative on any error condition
+ *
  * Read, modify, and if any change, write the register value back to the
  * device. Any error returns a negative number.
  *
@@ -599,6 +613,8 @@ static int __mdiobus_c45_modify_changed(struct mii_bus *bus, int addr,
  * @addr: the phy address
  * @regnum: register number to read
  *
+ * Return: The register value if successful, negative error code on failure
+ *
  * In case of nested MDIO bus access avoid lockdep false positives by
  * using mutex_lock_nested().
  *
@@ -624,6 +640,8 @@ EXPORT_SYMBOL(mdiobus_read_nested);
  * @addr: the phy address
  * @regnum: register number to read
  *
+ * Return: The register value if successful, negative error code on failure
+ *
  * NOTE: MUST NOT be called from interrupt context,
  * because the bus read/write functions may wait for an interrupt
  * to conclude the operation.
@@ -647,6 +665,8 @@ EXPORT_SYMBOL(mdiobus_read);
  * @devad: device address to read
  * @regnum: register number to read
  *
+ * Return: The register value if successful, negative error code on failure
+ *
  * NOTE: MUST NOT be called from interrupt context,
  * because the bus read/write functions may wait for an interrupt
  * to conclude the operation.
@@ -670,6 +690,8 @@ EXPORT_SYMBOL(mdiobus_c45_read);
  * @devad: device address to read
  * @regnum: register number to read
  *
+ * Return: The register value if successful, negative error code on failure
+ *
  * In case of nested MDIO bus access avoid lockdep false positives by
  * using mutex_lock_nested().
  *
@@ -697,6 +719,8 @@ EXPORT_SYMBOL(mdiobus_c45_read_nested);
  * @regnum: register number to write
  * @val: value to write to @regnum
  *
+ * Return: Zero if successful, negative error code on failure
+ *
  * In case of nested MDIO bus access avoid lockdep false positives by
  * using mutex_lock_nested().
  *
@@ -723,6 +747,8 @@ EXPORT_SYMBOL(mdiobus_write_nested);
  * @regnum: register number to write
  * @val: value to write to @regnum
  *
+ * Return: Zero if successful, negative error code on failure
+ *
  * NOTE: MUST NOT be called from interrupt context,
  * because the bus read/write functions may wait for an interrupt
  * to conclude the operation.
@@ -747,6 +773,8 @@ EXPORT_SYMBOL(mdiobus_write);
  * @regnum: register number to write
  * @val: value to write to @regnum
  *
+ * Return: Zero if successful, negative error code on failure
+ *
  * NOTE: MUST NOT be called from interrupt context,
  * because the bus read/write functions may wait for an interrupt
  * to conclude the operation.
@@ -772,6 +800,8 @@ EXPORT_SYMBOL(mdiobus_c45_write);
  * @regnum: register number to write
  * @val: value to write to @regnum
  *
+ * Return: Zero if successful, negative error code on failure
+ *
  * In case of nested MDIO bus access avoid lockdep false positives by
  * using mutex_lock_nested().
  *
@@ -800,6 +830,8 @@ EXPORT_SYMBOL(mdiobus_c45_write_nested);
  * @regnum: register number to write
  * @mask: bit mask of bits to clear
  * @set: bit mask of bits to set
+ *
+ * Return: 0 on success, negative on any error condition
  */
 int __mdiobus_modify(struct mii_bus *bus, int addr, u32 regnum, u16 mask,
 		     u16 set)
@@ -820,6 +852,8 @@ EXPORT_SYMBOL_GPL(__mdiobus_modify);
  * @regnum: register number to write
  * @mask: bit mask of bits to clear
  * @set: bit mask of bits to set
+ *
+ * Return: 0 on success, negative on any error condition
  */
 int mdiobus_modify(struct mii_bus *bus, int addr, u32 regnum, u16 mask, u16 set)
 {
@@ -842,6 +876,8 @@ EXPORT_SYMBOL_GPL(mdiobus_modify);
  * @regnum: register number to write
  * @mask: bit mask of bits to clear
  * @set: bit mask of bits to set
+ *
+ * Return: 0 on success, negative on any error condition
  */
 int mdiobus_c45_modify(struct mii_bus *bus, int addr, int devad, u32 regnum,
 		       u16 mask, u16 set)
@@ -865,6 +901,9 @@ EXPORT_SYMBOL_GPL(mdiobus_c45_modify);
  * @regnum: register number to write
  * @mask: bit mask of bits to clear
  * @set: bit mask of bits to set
+ *
+ * Return: 1 if the register was modified, 0 if no change was needed,
+ *	   negative on any error condition
  */
 int mdiobus_modify_changed(struct mii_bus *bus, int addr, u32 regnum,
 			   u16 mask, u16 set)
@@ -888,6 +927,9 @@ EXPORT_SYMBOL_GPL(mdiobus_modify_changed);
  * @regnum: register number to write
  * @mask: bit mask of bits to clear
  * @set: bit mask of bits to set
+ *
+ * Return: 1 if the register was modified, 0 if no change was needed,
+ *	   negative on any error condition
  */
 int mdiobus_c45_modify_changed(struct mii_bus *bus, int addr, int devad,
 			       u32 regnum, u16 mask, u16 set)
@@ -908,10 +950,10 @@ EXPORT_SYMBOL_GPL(mdiobus_c45_modify_changed);
  * @dev: target MDIO device
  * @drv: given MDIO driver
  *
- * Description: Given a MDIO device, and a MDIO driver, return 1 if
- *   the driver supports the device.  Otherwise, return 0. This may
- *   require calling the devices own match function, since different classes
- *   of MDIO devices have different match criteria.
+ * Return: 1 if the driver supports the device, 0 otherwise
+ *
+ * Description: This may require calling the devices own match function,
+ *   since different classes of MDIO devices have different match criteria.
  */
 static int mdio_bus_match(struct device *dev, const struct device_driver *drv)
 {
diff --git a/drivers/net/phy/mdio_device.c b/drivers/net/phy/mdio_device.c
index fd0e16dbc5cc..6e90ed42cd98 100644
--- a/drivers/net/phy/mdio_device.c
+++ b/drivers/net/phy/mdio_device.c
@@ -78,6 +78,8 @@ EXPORT_SYMBOL(mdio_device_create);
 /**
  * mdio_device_register - Register the mdio device on the MDIO bus
  * @mdiodev: mdio_device structure to be added to the MDIO bus
+ *
+ * Return: Zero if successful, negative error code on failure
  */
 int mdio_device_register(struct mdio_device *mdiodev)
 {
@@ -206,6 +208,8 @@ EXPORT_SYMBOL(mdio_device_reset);
  *
  * Description: Take care of setting up the mdio_device structure
  * and calling the driver to probe the device.
+ *
+ * Return: Zero if successful, negative error code on failure
  */
 static int mdio_probe(struct device *dev)
 {
@@ -256,6 +260,8 @@ static void mdio_shutdown(struct device *dev)
 /**
  * mdio_driver_register - register an mdio_driver with the MDIO layer
  * @drv: new mdio_driver to register
+ *
+ * Return: Zero if successful, negative error code on failure
  */
 int mdio_driver_register(struct mdio_driver *drv)
 {