From bff37a3a6cc480cf5cd34909c28c979907ba175f Mon Sep 17 00:00:00 2001
From: Daniel Leung <daniel.leung@intel.com>
Date: Thu, 6 Jan 2022 16:43:40 -0800
Subject: [PATCH] drivers: serial: remove @return doc for void functions

For functions returning nothing, there is no need to document
with @return, as Doxgen complains about "documented empty
return type of ...".

Signed-off-by: Daniel Leung <daniel.leung@intel.com>
---
 drivers/serial/uart_cc32xx.c     |  2 --
 drivers/serial/uart_cmsdk_apb.c  | 18 ------------------
 drivers/serial/uart_imx.c        |  2 --
 drivers/serial/uart_liteuart.c   | 10 ----------
 drivers/serial/uart_mchp_xec.c   | 14 --------------
 drivers/serial/uart_msp432p4xx.c |  2 --
 drivers/serial/uart_nrfx_uart.c  |  5 ++---
 drivers/serial/uart_nrfx_uarte.c |  2 --
 drivers/serial/uart_ns16550.c    | 14 --------------
 drivers/serial/uart_rcar.c       |  2 --
 drivers/serial/uart_sifive.c     | 10 ----------
 drivers/serial/uart_stellaris.c  | 24 ------------------------
 drivers/serial/uart_xlnx_ps.c    | 14 --------------
 include/drivers/uart.h           |  4 +---
 14 files changed, 3 insertions(+), 120 deletions(-)

diff --git a/drivers/serial/uart_cc32xx.c b/drivers/serial/uart_cc32xx.c
index e84ec87d1c0..c12befea4b2 100644
--- a/drivers/serial/uart_cc32xx.c
+++ b/drivers/serial/uart_cc32xx.c
@@ -259,8 +259,6 @@ static void uart_cc32xx_irq_callback_set(const struct device *dev,
  * received.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 static void uart_cc32xx_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_cmsdk_apb.c b/drivers/serial/uart_cmsdk_apb.c
index 5688351ec60..5d1c2ebface 100644
--- a/drivers/serial/uart_cmsdk_apb.c
+++ b/drivers/serial/uart_cmsdk_apb.c
@@ -94,8 +94,6 @@ static void uart_cmsdk_apb_isr(const struct device *dev);
  * This routine set the given baud rate for the UART.
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void baudrate_set(const struct device *dev)
 {
@@ -275,8 +273,6 @@ static int uart_cmsdk_apb_fifo_read(const struct device *dev,
  * @brief Enable TX interrupt
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_cmsdk_apb_irq_tx_enable(const struct device *dev)
 {
@@ -300,8 +296,6 @@ static void uart_cmsdk_apb_irq_tx_enable(const struct device *dev)
  * @brief Disable TX interrupt
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_cmsdk_apb_irq_tx_disable(const struct device *dev)
 {
@@ -326,8 +320,6 @@ static int uart_cmsdk_apb_irq_tx_ready(const struct device *dev)
  * @brief Enable RX interrupt
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_cmsdk_apb_irq_rx_enable(const struct device *dev)
 {
@@ -338,8 +330,6 @@ static void uart_cmsdk_apb_irq_rx_enable(const struct device *dev)
  * @brief Disable RX interrupt
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_cmsdk_apb_irq_rx_disable(const struct device *dev)
 {
@@ -376,8 +366,6 @@ static int uart_cmsdk_apb_irq_rx_ready(const struct device *dev)
  * @brief Enable error interrupt
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_cmsdk_apb_irq_err_enable(const struct device *dev)
 {
@@ -388,8 +376,6 @@ static void uart_cmsdk_apb_irq_err_enable(const struct device *dev)
  * @brief Disable error interrupt
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_cmsdk_apb_irq_err_disable(const struct device *dev)
 {
@@ -425,8 +411,6 @@ static int uart_cmsdk_apb_irq_update(const struct device *dev)
  *
  * @param dev UART device structure
  * @param cb Callback function pointer.
- *
- * @return N/A
  */
 static void uart_cmsdk_apb_irq_callback_set(const struct device *dev,
 					    uart_irq_callback_user_data_t cb,
@@ -442,8 +426,6 @@ static void uart_cmsdk_apb_irq_callback_set(const struct device *dev,
  * Calls the callback function, if exists.
  *
  * @param arg argument to interrupt service routine.
- *
- * @return N/A
  */
 void uart_cmsdk_apb_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_imx.c b/drivers/serial/uart_imx.c
index d120d932969..6921ceae1af 100644
--- a/drivers/serial/uart_imx.c
+++ b/drivers/serial/uart_imx.c
@@ -247,8 +247,6 @@ static void uart_imx_irq_callback_set(const struct device *dev,
  * received.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 void uart_imx_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_liteuart.c b/drivers/serial/uart_liteuart.c
index fc55e2a1843..d3e0b745002 100644
--- a/drivers/serial/uart_liteuart.c
+++ b/drivers/serial/uart_liteuart.c
@@ -90,8 +90,6 @@ static int uart_liteuart_poll_in(const struct device *dev, unsigned char *c)
  * @brief Enable TX interrupt in event register
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_liteuart_irq_tx_enable(const struct device *dev)
 {
@@ -104,8 +102,6 @@ static void uart_liteuart_irq_tx_enable(const struct device *dev)
  * @brief Disable TX interrupt in event register
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_liteuart_irq_tx_disable(const struct device *dev)
 {
@@ -118,8 +114,6 @@ static void uart_liteuart_irq_tx_disable(const struct device *dev)
  * @brief Enable RX interrupt in event register
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_liteuart_irq_rx_enable(const struct device *dev)
 {
@@ -132,8 +126,6 @@ static void uart_liteuart_irq_rx_enable(const struct device *dev)
  * @brief Disable RX interrupt in event register
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_liteuart_irq_rx_disable(const struct device *dev)
 {
@@ -258,8 +250,6 @@ static int uart_liteuart_irq_update(const struct device *dev)
  *
  * @param dev UART device struct
  * @param cb Callback function pointer.
- *
- * @return N/A
  */
 static void uart_liteuart_irq_callback_set(const struct device *dev,
 					   uart_irq_callback_user_data_t cb,
diff --git a/drivers/serial/uart_mchp_xec.c b/drivers/serial/uart_mchp_xec.c
index 0f329580ea2..ab0d7e0b812 100644
--- a/drivers/serial/uart_mchp_xec.c
+++ b/drivers/serial/uart_mchp_xec.c
@@ -516,8 +516,6 @@ static int uart_xec_fifo_read(const struct device *dev, uint8_t *rx_data,
  * @brief Enable TX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xec_irq_tx_enable(const struct device *dev)
 {
@@ -534,8 +532,6 @@ static void uart_xec_irq_tx_enable(const struct device *dev)
  * @brief Disable TX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xec_irq_tx_disable(const struct device *dev)
 {
@@ -591,8 +587,6 @@ static int uart_xec_irq_tx_complete(const struct device *dev)
  * @brief Enable RX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xec_irq_rx_enable(const struct device *dev)
 {
@@ -609,8 +603,6 @@ static void uart_xec_irq_rx_enable(const struct device *dev)
  * @brief Disable RX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xec_irq_rx_disable(const struct device *dev)
 {
@@ -645,8 +637,6 @@ static int uart_xec_irq_rx_ready(const struct device *dev)
  * @brief Enable error interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xec_irq_err_enable(const struct device *dev)
 {
@@ -720,8 +710,6 @@ static int uart_xec_irq_update(const struct device *dev)
  *
  * @param dev UART device struct
  * @param cb Callback function pointer.
- *
- * @return N/A
  */
 static void uart_xec_irq_callback_set(const struct device *dev,
 				      uart_irq_callback_user_data_t cb,
@@ -742,8 +730,6 @@ static void uart_xec_irq_callback_set(const struct device *dev,
  * This simply calls the callback function, if one exists.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 static void uart_xec_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_msp432p4xx.c b/drivers/serial/uart_msp432p4xx.c
index f6f4e4f51a0..a821b82a509 100644
--- a/drivers/serial/uart_msp432p4xx.c
+++ b/drivers/serial/uart_msp432p4xx.c
@@ -314,8 +314,6 @@ static void uart_msp432p4xx_irq_callback_set(const struct device *dev,
  * This simply calls the callback function, if one exists.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 static void uart_msp432p4xx_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_nrfx_uart.c b/drivers/serial/uart_nrfx_uart.c
index ac531be5859..f33b8265c69 100644
--- a/drivers/serial/uart_nrfx_uart.c
+++ b/drivers/serial/uart_nrfx_uart.c
@@ -192,7 +192,8 @@ static void event_txdrdy_clear(void)
  * @param dev UART device struct
  * @param baudrate Baud rate
  *
- * @return N/A
+ * @retval 0 on success.
+ * @retval -EINVAL for invalid baudrate.
  */
 
 static int baudrate_set(const struct device *dev, uint32_t baudrate)
@@ -1001,8 +1002,6 @@ static void uart_nrfx_irq_callback_set(const struct device *dev,
  * This simply calls the callback function, if one exists.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 static void uart_nrfx_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_nrfx_uarte.c b/drivers/serial/uart_nrfx_uarte.c
index 1bb8378c4c9..08bd8d552d3 100644
--- a/drivers/serial/uart_nrfx_uarte.c
+++ b/drivers/serial/uart_nrfx_uarte.c
@@ -262,8 +262,6 @@ static void endtx_isr(const struct device *dev)
  * This simply calls the callback function, if one exists.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 static void uarte_nrfx_isr_int(void *arg)
 {
diff --git a/drivers/serial/uart_ns16550.c b/drivers/serial/uart_ns16550.c
index 246ee66b710..51f9f34f6cd 100644
--- a/drivers/serial/uart_ns16550.c
+++ b/drivers/serial/uart_ns16550.c
@@ -655,8 +655,6 @@ static int uart_ns16550_fifo_read(const struct device *dev, uint8_t *rx_data,
  * @brief Enable TX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_ns16550_irq_tx_enable(const struct device *dev)
 {
@@ -691,8 +689,6 @@ static void uart_ns16550_irq_tx_enable(const struct device *dev)
  * @brief Disable TX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_ns16550_irq_tx_disable(const struct device *dev)
 {
@@ -764,8 +760,6 @@ static int uart_ns16550_irq_tx_complete(const struct device *dev)
  * @brief Enable RX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_ns16550_irq_rx_enable(const struct device *dev)
 {
@@ -780,8 +774,6 @@ static void uart_ns16550_irq_rx_enable(const struct device *dev)
  * @brief Disable RX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_ns16550_irq_rx_disable(const struct device *dev)
 {
@@ -814,8 +806,6 @@ static int uart_ns16550_irq_rx_ready(const struct device *dev)
  * @brief Enable error interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_ns16550_irq_err_enable(const struct device *dev)
 {
@@ -883,8 +873,6 @@ static int uart_ns16550_irq_update(const struct device *dev)
  *
  * @param dev UART device struct
  * @param cb Callback function pointer.
- *
- * @return N/A
  */
 static void uart_ns16550_irq_callback_set(const struct device *dev,
 					  uart_irq_callback_user_data_t cb,
@@ -905,8 +893,6 @@ static void uart_ns16550_irq_callback_set(const struct device *dev,
  * This simply calls the callback function, if one exists.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 static void uart_ns16550_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_rcar.c b/drivers/serial/uart_rcar.c
index 2ffc96ffb95..629da499e41 100644
--- a/drivers/serial/uart_rcar.c
+++ b/drivers/serial/uart_rcar.c
@@ -489,8 +489,6 @@ static void uart_rcar_irq_callback_set(const struct device *dev,
  * This simply calls the callback function, if one exists.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 void uart_rcar_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_sifive.c b/drivers/serial/uart_sifive.c
index 75cc9c464f4..c52c882167b 100644
--- a/drivers/serial/uart_sifive.c
+++ b/drivers/serial/uart_sifive.c
@@ -171,8 +171,6 @@ static int uart_sifive_fifo_read(const struct device *dev,
  * @brief Enable TX interrupt in ie register
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_sifive_irq_tx_enable(const struct device *dev)
 {
@@ -185,8 +183,6 @@ static void uart_sifive_irq_tx_enable(const struct device *dev)
  * @brief Disable TX interrupt in ie register
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_sifive_irq_tx_disable(const struct device *dev)
 {
@@ -231,8 +227,6 @@ static int uart_sifive_irq_tx_complete(const struct device *dev)
  * @brief Enable RX interrupt in ie register
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_sifive_irq_rx_enable(const struct device *dev)
 {
@@ -245,8 +239,6 @@ static void uart_sifive_irq_rx_enable(const struct device *dev)
  * @brief Disable RX interrupt in ie register
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_sifive_irq_rx_disable(const struct device *dev)
 {
@@ -304,8 +296,6 @@ static int uart_sifive_irq_update(const struct device *dev)
  *
  * @param dev UART device struct
  * @param cb Callback function pointer.
- *
- * @return N/A
  */
 static void uart_sifive_irq_callback_set(const struct device *dev,
 					 uart_irq_callback_user_data_t cb,
diff --git a/drivers/serial/uart_stellaris.c b/drivers/serial/uart_stellaris.c
index b5c71269e2c..8309ea7379e 100644
--- a/drivers/serial/uart_stellaris.c
+++ b/drivers/serial/uart_stellaris.c
@@ -156,8 +156,6 @@ static const struct uart_driver_api uart_stellaris_driver_api;
  * @param dev UART device struct
  * @param baudrate Baud rate
  * @param sys_clk_freq_hz System clock frequency in Hz
- *
- * @return N/A
  */
 static void baudrate_set(const struct device *dev,
 			 uint32_t baudrate, uint32_t sys_clk_freq_hz)
@@ -193,8 +191,6 @@ static void baudrate_set(const struct device *dev,
  * This routine enables the given UART.
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static inline void enable(const struct device *dev)
 {
@@ -209,8 +205,6 @@ static inline void enable(const struct device *dev)
  * This routine disables the given UART.
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static inline void disable(const struct device *dev)
 {
@@ -242,8 +236,6 @@ static inline void disable(const struct device *dev)
  * This routine sets the given UART's line controls to their default settings.
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static inline void line_control_defaults_set(const struct device *dev)
 {
@@ -389,8 +381,6 @@ static int uart_stellaris_fifo_read(const struct device *dev,
  * @brief Enable TX interrupt
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_stellaris_irq_tx_enable(const struct device *dev)
 {
@@ -443,8 +433,6 @@ static void uart_stellaris_irq_tx_enable(const struct device *dev)
  * @brief Disable TX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_stellaris_irq_tx_disable(const struct device *dev)
 {
@@ -471,8 +459,6 @@ static int uart_stellaris_irq_tx_ready(const struct device *dev)
  * @brief Enable RX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_stellaris_irq_rx_enable(const struct device *dev)
 {
@@ -485,8 +471,6 @@ static void uart_stellaris_irq_rx_enable(const struct device *dev)
  * @brief Disable RX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_stellaris_irq_rx_disable(const struct device *dev)
 {
@@ -513,8 +497,6 @@ static int uart_stellaris_irq_rx_ready(const struct device *dev)
  * @brief Enable error interrupts
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_stellaris_irq_err_enable(const struct device *dev)
 {
@@ -528,8 +510,6 @@ static void uart_stellaris_irq_err_enable(const struct device *dev)
  * @brief Disable error interrupts
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_stellaris_irq_err_disable(const struct device *dev)
 {
@@ -571,8 +551,6 @@ static int uart_stellaris_irq_update(const struct device *dev)
  *
  * @param dev UART device struct
  * @param cb Callback function pointer.
- *
- * @return N/A
  */
 static void uart_stellaris_irq_callback_set(const struct device *dev,
 					    uart_irq_callback_user_data_t cb,
@@ -590,8 +568,6 @@ static void uart_stellaris_irq_callback_set(const struct device *dev,
  * This simply calls the callback function, if one exists.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 static void uart_stellaris_isr(const struct device *dev)
 {
diff --git a/drivers/serial/uart_xlnx_ps.c b/drivers/serial/uart_xlnx_ps.c
index 49ce4a30cef..19ed49fa1a9 100644
--- a/drivers/serial/uart_xlnx_ps.c
+++ b/drivers/serial/uart_xlnx_ps.c
@@ -890,8 +890,6 @@ static int uart_xlnx_ps_fifo_read(const struct device *dev, uint8_t *rx_data,
  * @brief Enable TX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xlnx_ps_irq_tx_enable(const struct device *dev)
 {
@@ -908,8 +906,6 @@ static void uart_xlnx_ps_irq_tx_enable(const struct device *dev)
  * @brief Disable TX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xlnx_ps_irq_tx_disable(const struct device *dev)
 {
@@ -968,8 +964,6 @@ static int uart_xlnx_ps_irq_tx_complete(const struct device *dev)
  * @brief Enable RX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xlnx_ps_irq_rx_enable(const struct device *dev)
 {
@@ -984,8 +978,6 @@ static void uart_xlnx_ps_irq_rx_enable(const struct device *dev)
  * @brief Disable RX interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xlnx_ps_irq_rx_disable(const struct device *dev)
 {
@@ -1021,8 +1013,6 @@ static int uart_xlnx_ps_irq_rx_ready(const struct device *dev)
  * @brief Enable error interrupt in IER
  *
  * @param dev UART device struct
- *
- * @return N/A
  */
 static void uart_xlnx_ps_irq_err_enable(const struct device *dev)
 {
@@ -1104,8 +1094,6 @@ static int uart_xlnx_ps_irq_update(const struct device *dev)
  *
  * @param dev UART device struct
  * @param cb Callback function pointer.
- *
- * @return N/A
  */
 static void uart_xlnx_ps_irq_callback_set(const struct device *dev,
 					    uart_irq_callback_user_data_t cb,
@@ -1123,8 +1111,6 @@ static void uart_xlnx_ps_irq_callback_set(const struct device *dev,
  * This simply calls the callback function, if one exists.
  *
  * @param arg Argument to ISR.
- *
- * @return N/A
  */
 static void uart_xlnx_ps_isr(const struct device *dev)
 {
diff --git a/include/drivers/uart.h b/include/drivers/uart.h
index 8264dfb6fa9..4b50b7385a8 100644
--- a/include/drivers/uart.h
+++ b/include/drivers/uart.h
@@ -867,6 +867,7 @@ static inline void z_impl_uart_irq_tx_enable(const struct device *dev)
 	}
 #endif
 }
+
 /**
  * @brief Disable TX interrupt in IER.
  *
@@ -1049,9 +1050,6 @@ static inline void z_impl_uart_irq_err_enable(const struct device *dev)
  * @brief Disable error interrupt.
  *
  * @param dev UART device instance.
- *
- * @retval 1 If an IRQ is ready.
- * @retval 0 Otherwise.
  */
 __syscall void uart_irq_err_disable(const struct device *dev);