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

Author: supperthomas

.github/workflows/doxygen.yml

@@ -3,27 +3,13 @@ on:
   # Runs at 16:00 UTC (BeiJing 00:00) on the 30st of every month
   schedule:
     - cron:  '0 16 30 * *'
-  push:
-    branches:
-      - master
-    paths-ignore:
-      - '**/README.md'
-      - '**/README_zh.md'
-  pull_request:
-    branches:
-      - master
-    paths-ignore:
-      - bsp/**
-      - examples/**
-      - .github/**
-      - '**/README.md'
-      - '**/README_zh.md'
+  workflow_dispatch:
 
 jobs:
   build:
     runs-on: ubuntu-latest
     name: doxygen_doc generate
-    if: github.repository_owner == 'RT-Thread' && false
+    if: github.repository_owner == 'RT-Thread'
     steps:
       - uses: actions/checkout@v4
         with:

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*/

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