[doxygen] add driver example for doxygen (#9446)

3 files changed, 302 insertions, 15 deletions

diff --git a/components/drivers/include/drivers/dev_can.h b/components/drivers/include/drivers/dev_can.h
index 9f2d7c0677..6881d5d613 100644
--- a/components/drivers/include/drivers/dev_can.h
+++ b/components/drivers/include/drivers/dev_can.h
@@ -63,9 +63,16 @@ enum CANBAUD
 #define RT_CAN_MODE_PRIV                0x01
 #define RT_CAN_MODE_NOPRIV              0x00
 
-/** @defgroup CAN_receive_FIFO_number CAN Receive FIFO Number
-  * @{
-  */
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    CAN_Device          CAN Driver
+ * @ingroup     Drivers
+ */
+
+/*!
+ * @addtogroup CAN_Device
+ * @{
+ */
 #define CAN_RX_FIFO0                (0x00000000U)  /*!< CAN receive FIFO 0 */
 #define CAN_RX_FIFO1                (0x00000001U)  /*!< CAN receive FIFO 1 */
 
@@ -360,5 +367,8 @@ rt_err_t rt_hw_can_register(struct rt_can_device    *can,
                             const struct rt_can_ops *ops,
                             void                    *data);
 void rt_hw_can_isr(struct rt_can_device *can, int event);
-#endif /*__DEV_CAN_H*/
 
+/*! @}
+*/
+
+#endif /*__DEV_CAN_H*/
\ No newline at end of file
diff --git a/components/drivers/include/drivers/dev_serial.h b/components/drivers/include/drivers/dev_serial.h
index 418c25fa1d..df2a62030a 100644
--- a/components/drivers/include/drivers/dev_serial.h
+++ b/components/drivers/include/drivers/dev_serial.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2024, RT-Thread Development Team
+ * Copyright (c) 2006-2024 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -15,7 +15,105 @@
 #define __DEV_SERIAL_H__
 
 #include <rtthread.h>
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    Serial           Serial
+ *
+ * @brief       Serial driver api
+ *
+ * <b>Example</b>
+ * @code {.c}
+ *
+ * #include <rtthread.h>
+ *
+ * #define SAMPLE_UART_NAME       "uart2"
+ * static struct rt_semaphore rx_sem;
+ * static rt_device_t serial;
+ *
+ * static rt_err_t uart_input(rt_device_t dev, rt_size_t size)
+ * {
+ *
+ *     rt_sem_release(&rx_sem);
+ *
+ *     return RT_EOK;
+ * }
+ *
+ * static void serial_thread_entry(void *parameter)
+ * {
+ *     char ch;
+ *
+ *     while (1)
+ *     {
+ *
+ *         while (rt_device_read(serial, -1, &ch, 1) != 1)
+ *         {
+ *
+ *             rt_sem_take(&rx_sem, RT_WAITING_FOREVER);
+ *         }
+ *
+ *         ch = ch + 1;
+ *         rt_device_write(serial, 0, &ch, 1);
+ *     }
+ * }
+ *
+ * static int uart_sample(int argc, char *argv[])
+ * {
+ *     rt_err_t ret = RT_EOK;
+ *     char uart_name[RT_NAME_MAX];
+ *     char str[] = "hello RT-Thread!\r\n";
+ *
+ *     if (argc == 2)
+ *     {
+ *         rt_strncpy(uart_name, argv[1], RT_NAME_MAX);
+ *     }
+ *     else
+ *     {
+ *         rt_strncpy(uart_name, SAMPLE_UART_NAME, RT_NAME_MAX);
+ *     }
+ *
+ *
+ *     serial = rt_device_find(uart_name);
+ *     if (!serial)
+ *     {
+ *         rt_kprintf("find %s failed!\n", uart_name);
+ *         return RT_ERROR;
+ *     }
+ *
+ *
+ *     rt_sem_init(&rx_sem, "rx_sem", 0, RT_IPC_FLAG_FIFO);
+ *
+ *     rt_device_open(serial, RT_DEVICE_FLAG_INT_RX);
+ *
+ *     rt_device_set_rx_indicate(serial, uart_input);
+ *
+ *     rt_device_write(serial, 0, str, (sizeof(str) - 1));
+ *
+ *
+ *     rt_thread_t thread = rt_thread_create("serial", serial_thread_entry, RT_NULL, 1024, 25, 10);
+ *
+ *     if (thread != RT_NULL)
+ *     {
+ *         rt_thread_startup(thread);
+ *     }
+ *     else
+ *     {
+ *         ret = RT_ERROR;
+ *     }
+ *
+ *     return ret;
+ * }
+ *
+ * MSH_CMD_EXPORT(uart_sample, uart device sample);
+ * @endcode
+ *
+ * @ingroup     Drivers
+ */
 
+
+/*!
+ * @addtogroup Serial
+ * @{
+ */
 #define BAUD_RATE_2400                  2400
 #define BAUD_RATE_4800                  4800
 #define BAUD_RATE_9600                  9600
@@ -105,7 +203,6 @@
 /**
  * @brief Sets a hook function when RX indicate is called
  *
- * @param thread is the target thread that initializing
  */
 typedef void (*rt_hw_serial_rxind_hookproto_t)(rt_device_t dev, rt_size_t size);
 RT_OBJECT_HOOKLIST_DECLARE(rt_hw_serial_rxind_hookproto_t, rt_hw_serial_rxind);
@@ -173,7 +270,7 @@ struct rt_serial_device
 typedef struct rt_serial_device rt_serial_t;
 
 /**
- * uart operators
+ * @brief Configure the serial device
  */
 struct rt_uart_ops
 {
@@ -186,13 +283,41 @@ struct rt_uart_ops
     rt_ssize_t (*dma_transmit)(struct rt_serial_device *serial, rt_uint8_t *buf, rt_size_t size, int direction);
 };
 
+/**
+ * @brief Serial interrupt service routine
+ * @param serial    serial device
+ * @param event     event mask
+ * @ingroup  Serial
+ */
 void rt_hw_serial_isr(struct rt_serial_device *serial, int event);
 
+/**
+ * @brief Register a serial device to device list
+ *
+ * @param serial    serial device
+ * @param name      device name
+ * @param flag      device flag
+ * @param data      device private data
+ * @return rt_err_t        error code
+ * @note This function will register a serial device to system device list,
+ *       and add a device object to system object list.
+ * @ingroup  Serial
+ */
 rt_err_t rt_hw_serial_register(struct rt_serial_device *serial,
                                const char              *name,
                                rt_uint32_t              flag,
                                void                    *data);
 
+/**
+ * @brief     register a serial device to system device list and add a device object to system object list
+ *
+ * @param serial    serial device
+ * @return rt_err_t error code
+ *
+ * @ingroup  Serial
+ */
 rt_err_t rt_hw_serial_register_tty(struct rt_serial_device *serial);
 
+/*! @}*/
+
 #endif
diff --git a/components/drivers/include/drivers/dev_serial_v2.h b/components/drivers/include/drivers/dev_serial_v2.h
index 0c3d095ab3..0bdc51b7ba 100644
--- a/components/drivers/include/drivers/dev_serial_v2.h
+++ b/components/drivers/include/drivers/dev_serial_v2.h
@@ -13,6 +13,122 @@
 
 #include <rtthread.h>
 
+
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    Serial_v2       Serial v2
+ *
+ * @brief       Serial v2 driver api
+ * 
+ * <b>Example</b>
+ * @code {.c}
+ * 
+ * #include <rtthread.h>
+ * #include <rtdevice.h>
+ * 
+ * #define SAMPLE_UART_NAME       "uart1"      
+ * 
+ * struct rx_msg
+ * {
+ *     rt_device_t dev;
+ *     rt_size_t size;
+ * };
+ * static rt_device_t serial;
+ * static struct rt_messagequeue rx_mq;
+ * 
+ * static rt_err_t uart_input(rt_device_t dev, rt_size_t size)
+ * {
+ *     struct rx_msg msg;
+ *     rt_err_t result;
+ *     msg.dev = dev;
+ *     msg.size = size;
+ * 
+ *     result = rt_mq_send(&rx_mq, &msg, sizeof(msg));
+ *     if (result == -RT_EFULL)
+ *     {
+ *         rt_kprintf("message queue full！\n");
+ *     }
+ *     return result;
+ * }
+ * 
+ * static void serial_thread_entry(void *parameter)
+ * {
+ *     struct rx_msg msg;
+ *     rt_err_t result;
+ *     rt_uint32_t rx_length;
+ *     static char rx_buffer[BSP_UART1_RX_BUFSIZE + 1];
+ * 
+ *     while (1)
+ *     {
+ *         rt_memset(&msg, 0, sizeof(msg));
+ *         result = rt_mq_recv(&rx_mq, &msg, sizeof(msg), RT_WAITING_FOREVER);
+ *         if (result > 0)
+ *         {
+ *             rx_length = rt_device_read(msg.dev, 0, rx_buffer, msg.size);
+ *             rx_buffer[rx_length] = '\0';
+ *             rt_device_write(serial, 0, rx_buffer, rx_length);
+ *             rt_kprintf("%s\n",rx_buffer);
+ *         }
+ *     }
+ * }
+ * 
+ * static int uart_dma_sample(int argc, char *argv[])
+ * {
+ *     rt_err_t ret = RT_EOK;
+ *     char uart_name[RT_NAME_MAX];
+ *     static char msg_pool[256];
+ *     char str[] = "hello RT-Thread!\r\n";
+ * 
+ *     if (argc == 2)
+ *     {
+ *         rt_strncpy(uart_name, argv[1], RT_NAME_MAX);
+ *     }
+ *     else
+ *     {
+ *         rt_strncpy(uart_name, SAMPLE_UART_NAME, RT_NAME_MAX);
+ *     }
+ * 
+ *     serial = rt_device_find(uart_name);
+ *     if (!serial)
+ *     {
+ *         rt_kprintf("find %s failed!\n", uart_name);
+ *         return RT_ERROR;
+ *     }
+ * 
+ *     rt_mq_init(&rx_mq, "rx_mq",
+ *                msg_pool,                 
+ *                sizeof(struct rx_msg),    
+ *                sizeof(msg_pool),         
+ *                RT_IPC_FLAG_FIFO);       
+ * 
+ *     rt_device_open(serial, RT_DEVICE_FLAG_RX_NON_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING);
+ *     rt_device_set_rx_indicate(serial, uart_input);
+ *     rt_device_write(serial, 0, str, (sizeof(str) - 1));
+ * 
+ *     rt_thread_t thread = rt_thread_create("serial", serial_thread_entry, RT_NULL, 1024, 25, 10);
+ *     if (thread != RT_NULL)
+ *     {
+ *         rt_thread_startup(thread);
+ *     }
+ *     else
+ *     {
+ *         ret = RT_ERROR;
+ *     }
+ * 
+ *     return ret;
+ * }
+ * MSH_CMD_EXPORT(uart_dma_sample, uart device dma sample);
+ * @endcode
+ * 
+ * @ingroup     Drivers
+ */
+
+
+/*!
+ * @addtogroup Serial_v2
+ * @{
+ */
+
 #define BAUD_RATE_2400                  2400
 #define BAUD_RATE_4800                  4800
 #define BAUD_RATE_9600                  9600
@@ -104,9 +220,8 @@
 }
 
 /**
- * @brief Sets a hook function when RX indicate is called
- *
- * @param thread is the target thread that initializing
+ * @brief Serial receive indicate hook function type
+ * 
  */
 typedef void (*rt_hw_serial_rxind_hookproto_t)(rt_device_t dev, rt_size_t size);
 RT_OBJECT_HOOKLIST_DECLARE(rt_hw_serial_rxind_hookproto_t, rt_hw_serial_rxind);
@@ -126,8 +241,8 @@ struct serial_configure
     rt_uint32_t reserved                :5;
 };
 
-/*
- * Serial Receive FIFO mode
+/**
+ * @brief Serial Receive FIFO mode
  */
 struct rt_serial_rx_fifo
 {
@@ -141,8 +256,9 @@ struct rt_serial_rx_fifo
     rt_uint8_t buffer[];
 };
 
-/*
- * Serial Transmit FIFO mode
+/**
+ * @brief Serial Transmit FIFO mode
+ * 
  */
 struct rt_serial_tx_fifo
 {
@@ -158,6 +274,10 @@ struct rt_serial_tx_fifo
     rt_uint8_t buffer[];
 };
 
+/**
+ * @brief     serial device structure
+ * 
+ */
 struct rt_serial_device
 {
     struct rt_device          parent;
@@ -172,7 +292,8 @@ struct rt_serial_device
 };
 
 /**
- * uart operators
+ * @brief uart device operations
+ * 
  */
 struct rt_uart_ops
 {
@@ -192,12 +313,43 @@ struct rt_uart_ops
                                  rt_uint32_t             tx_flag);
 };
 
+/**
+ * @brief Serial interrupt service routine
+ * @param serial    serial device
+ * @param event     event mask
+ * @ingroup  Serial_v2
+ */
 void rt_hw_serial_isr(struct rt_serial_device *serial, int event);
 
+
+/**
+ * @brief Register a serial device to device list
+ * 
+ * @param serial    serial device
+ * @param name      device name
+ * @param flag      device flag
+ * @param data      device private data
+ * @return rt_err_t        error code
+ * @note This function will register a serial device to system device list,
+ *       and add a device object to system object list.
+ * @ingroup  Serial_v2
+ */
 rt_err_t rt_hw_serial_register(struct rt_serial_device      *serial,
                                const  char                  *name,
                                       rt_uint32_t            flag,
                                       void                  *data);
 
+/**
+ * @brief     register a serial device to system device list and add a device object to system object list
+ * 
+ * @param serial    serial device
+ * @return rt_err_t error code
+ * 
+ * @ingroup  Serial_v2
+ */
 rt_err_t rt_hw_serial_register_tty(struct rt_serial_device *serial);
+
+
+/*! @}*/
+
 #endif