[PATCH] staging: octeon: Fix return value documentation warnings

[PATCH] staging: octeon: Fix return value documentation warnings

[Massi Djaiz]

Running "scripts/kernel-doc -none -Wall drivers/staging/octeon/" reports
that 17 functions in drivers/staging/octeon/ have a missing
description for their return value.

16 of the 17 functions have a return value description formatted as
"Returns [...description]".

1 function, cvm_oct_do_interrupt(), has no return value description.

Documentation/doc-guide/kernel-doc.rst states that if a function has a
return value, it should be described in a section named "Return".
Sections are only recognized if their name is followed by a ":".

- Replace each occurrence of "Returns" with "Return: ".
- Add a return value description to cvm_oct_do_interrupt(),
  which always returns the constant IRQ_HANDLED.

No functional change.

Signed-off-by: Massi Djaiz <djaizmassi@gmail.com>
---
 drivers/staging/octeon/ethernet-mdio.c |  4 ++--
 drivers/staging/octeon/ethernet-mem.c  |  4 ++--
 drivers/staging/octeon/ethernet-rx.c   |  5 +++--
 drivers/staging/octeon/ethernet-tx.c   |  4 ++--
 drivers/staging/octeon/ethernet-util.h |  6 +++---
 drivers/staging/octeon/ethernet.c      | 10 +++++-----
 6 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/drivers/staging/octeon/ethernet-mdio.c b/drivers/staging/octeon/ethernet-mdio.c
index 211423059e30..569e4aba38bc 100644
--- a/drivers/staging/octeon/ethernet-mdio.c
+++ b/drivers/staging/octeon/ethernet-mdio.c
@@ -49,7 +49,7 @@ const struct ethtool_ops cvm_oct_ethtool_ops = {
  * @rq:     the request
  * @cmd:    the command
  *
- * Returns Zero on success
+ * Return: Zero on success
  */
 int cvm_oct_ioctl(struct net_device *dev, struct ifreq *rq, int cmd)
 {
@@ -132,7 +132,7 @@ int cvm_oct_common_stop(struct net_device *dev)
  *
  * @dev:    Device to setup
  *
- * Returns Zero on success, negative on failure
+ * Return: Zero on success, negative on failure
  */
 int cvm_oct_phy_setup_device(struct net_device *dev)
 {
diff --git a/drivers/staging/octeon/ethernet-mem.c b/drivers/staging/octeon/ethernet-mem.c
index 68c3ef984e56..224a7189faf2 100644
--- a/drivers/staging/octeon/ethernet-mem.c
+++ b/drivers/staging/octeon/ethernet-mem.c
@@ -20,7 +20,7 @@
  * @size:     Size of the buffer needed for the pool
  * @elements: Number of buffers to allocate
  *
- * Returns the actual number of buffers allocated.
+ * Return: the actual number of buffers allocated.
  */
 static int cvm_oct_fill_hw_skbuff(int pool, int size, int elements)
 {
@@ -76,7 +76,7 @@ static void cvm_oct_free_hw_skbuff(struct platform_device *pdev,
  * @size:     Size of each buffer in the pool
  * @elements: Number of buffers to allocate
  *
- * Returns the actual number of buffers allocated.
+ * Return: the actual number of buffers allocated.
  */
 static int cvm_oct_fill_hw_memory(struct platform_device *pdev, int pool, int size,
 				  int elements)
diff --git a/drivers/staging/octeon/ethernet-rx.c b/drivers/staging/octeon/ethernet-rx.c
index 5be43bbf6a1d..5ca30f5b046d 100644
--- a/drivers/staging/octeon/ethernet-rx.c
+++ b/drivers/staging/octeon/ethernet-rx.c
@@ -41,6 +41,7 @@ static atomic_t oct_rx_ready = ATOMIC_INIT(0);
  *
  * The interrupt occurs whenever the POW has packets in our group.
  *
+ * Return: Always returns %IRQ_HANDLED.
  */
 static irqreturn_t cvm_oct_do_interrupt(int irq, void *napi_id)
 {
@@ -55,7 +56,7 @@ static irqreturn_t cvm_oct_do_interrupt(int irq, void *napi_id)
  * cvm_oct_check_rcv_error - process receive errors
  * @work: Work queue entry pointing to the packet.
  *
- * Returns Non-zero if the packet can be dropped, zero otherwise.
+ * Return: Non-zero if the packet can be dropped, zero otherwise.
  */
 static inline int cvm_oct_check_rcv_error(struct cvmx_wqe *work)
 {
@@ -404,7 +405,7 @@ static int cvm_oct_poll(struct oct_rx_group *rx_group, int budget)
  * @napi: The NAPI instance.
  * @budget: Maximum number of packets to receive.
  *
- * Returns the number of packets processed.
+ * Return: the number of packets processed.
  */
 static int cvm_oct_napi_poll(struct napi_struct *napi, int budget)
 {
diff --git a/drivers/staging/octeon/ethernet-tx.c b/drivers/staging/octeon/ethernet-tx.c
index 5e536827f87a..44534b94aec2 100644
--- a/drivers/staging/octeon/ethernet-tx.c
+++ b/drivers/staging/octeon/ethernet-tx.c
@@ -122,7 +122,7 @@ static void cvm_oct_free_tx_skbs(struct net_device *dev)
  * @skb:    Packet to send
  * @dev:    Device info structure
  *
- * Returns Always returns NETDEV_TX_OK
+ * Return: Always returns NETDEV_TX_OK
  */
 netdev_tx_t cvm_oct_xmit(struct sk_buff *skb, struct net_device *dev)
 {
@@ -500,7 +500,7 @@ netdev_tx_t cvm_oct_xmit(struct sk_buff *skb, struct net_device *dev)
  * cvm_oct_xmit_pow - transmit a packet to the POW
  * @skb:    Packet to send
  * @dev:    Device info structure
- * Returns Always returns zero
+ * Return: Always returns zero
  */
 netdev_tx_t cvm_oct_xmit_pow(struct sk_buff *skb, struct net_device *dev)
 {
diff --git a/drivers/staging/octeon/ethernet-util.h b/drivers/staging/octeon/ethernet-util.h
index 2af83a12ca78..510e04030c74 100644
--- a/drivers/staging/octeon/ethernet-util.h
+++ b/drivers/staging/octeon/ethernet-util.h
@@ -9,7 +9,7 @@
  * cvm_oct_get_buffer_ptr - convert packet data address to pointer
  * @packet_ptr: Packet data hardware address
  *
- * Returns Packet buffer pointer
+ * Return: Packet buffer pointer
  */
 static inline void *cvm_oct_get_buffer_ptr(union cvmx_buf_ptr packet_ptr)
 {
@@ -21,7 +21,7 @@ static inline void *cvm_oct_get_buffer_ptr(union cvmx_buf_ptr packet_ptr)
  * INTERFACE - convert IPD port to logical interface
  * @ipd_port: Port to check
  *
- * Returns Logical interface
+ * Return: Logical interface
  */
 static inline int INTERFACE(int ipd_port)
 {
@@ -39,7 +39,7 @@ static inline int INTERFACE(int ipd_port)
  * INDEX - convert IPD/PKO port number to the port's interface index
  * @ipd_port: Port to check
  *
- * Returns Index into interface port list
+ * Return: Index into interface port list
  */
 static inline int INDEX(int ipd_port)
 {
diff --git a/drivers/staging/octeon/ethernet.c b/drivers/staging/octeon/ethernet.c
index 42ec4b8324a8..463302cf5a61 100644
--- a/drivers/staging/octeon/ethernet.c
+++ b/drivers/staging/octeon/ethernet.c
@@ -183,7 +183,7 @@ static void cvm_oct_configure_common_hw(struct platform_device *pdev)
  *
  * @work_queue_entry: Work queue entry to free
  *
- * Returns Zero on success, Negative on failure.
+ * Return: Zero on success, Negative on failure.
  */
 int cvm_oct_free_work(void *work_queue_entry)
 {
@@ -211,7 +211,7 @@ EXPORT_SYMBOL(cvm_oct_free_work);
  * cvm_oct_common_get_stats - get the low level ethernet statistics
  * @dev:    Device to get the statistics from
  *
- * Returns Pointer to the statistics
+ * Return: Pointer to the statistics
  */
 static struct net_device_stats *cvm_oct_common_get_stats(struct net_device *dev)
 {
@@ -247,7 +247,7 @@ static struct net_device_stats *cvm_oct_common_get_stats(struct net_device *dev)
  * @dev:     Device to change
  * @new_mtu: The new MTU
  *
- * Returns Zero on success
+ * Return: Zero on success
  */
 static int cvm_oct_common_change_mtu(struct net_device *dev, int new_mtu)
 {
@@ -401,7 +401,7 @@ static int cvm_oct_set_mac_filter(struct net_device *dev)
  * @dev:    The device in question.
  * @addr:   Socket address.
  *
- * Returns Zero on success
+ * Return: Zero on success
  */
 static int cvm_oct_common_set_mac_address(struct net_device *dev, void *addr)
 {
@@ -416,7 +416,7 @@ static int cvm_oct_common_set_mac_address(struct net_device *dev, void *addr)
  * cvm_oct_common_init - per network device initialization
  * @dev:    Device to initialize
  *
- * Returns Zero on success
+ * Return: Zero on success
  */
 int cvm_oct_common_init(struct net_device *dev)
 {
-- 
2.43.0