From d55931493accc078cef64b4250eea6d34a67c5d0 Mon Sep 17 00:00:00 2001
From: CYFS <2805686936@qq.com>
Date: Wed, 25 Sep 2024 19:10:02 +0800
Subject: [PATCH] [doxygen]add dac driver example for doxygen

---
 components/drivers/include/drivers/dac.h | 89 +++++++++++++++++++++++-
 1 file changed, 88 insertions(+), 1 deletion(-)

diff --git a/components/drivers/include/drivers/dac.h b/components/drivers/include/drivers/dac.h
index c03fa10929..d7160dd936 100644
--- a/components/drivers/include/drivers/dac.h
+++ b/components/drivers/include/drivers/dac.h
@@ -11,8 +11,66 @@
 #ifndef __DAC_H__
 #define __DAC_H__
 #include <rtthread.h>
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    DAC           DAC
+ *
+ * @brief       DAC driver api
+ *
+ * <b>Example</b>
+ * @code {.c}
+ * 
+ * #include <rtthread.h>
+ * #include <rtdevice.h>
+ * #include <stdlib.h>
+ * #define DAC_DEV_NAME        "dac1" 
+ * #define DAC_DEV_CHANNEL     1      
+ * #define REFER_VOLTAGE       330    
+ * #define CONVERT_BITS        (1 << 12)  
+ * 
+ * static int dac_vol_sample(int argc, char *argv[])
+ * {
+ *     rt_dac_device_t dac_dev;
+ *     rt_uint32_t value, vol;
+ *     rt_err_t ret = RT_EOK;
+ * 
+ *     dac_dev = (rt_dac_device_t)rt_device_find(DAC_DEV_NAME);
+ *     if (dac_dev == RT_NULL)
+ *     {
+ *         rt_kprintf("dac sample run failed! can't find %s device!\n", DAC_DEV_NAME);
+ *         return RT_ERROR;
+ *     }
+ * 
+ *     ret = rt_dac_enable(dac_dev, DAC_DEV_CHANNEL);
+ * 
+ *     value = atoi(argv[1]);
+ *     rt_dac_write(dac_dev, DAC_DEV_NAME, DAC_DEV_CHANNEL, value);
+ *     rt_kprintf("the value is :%d \n", value);
+ * 
+ *     vol = value * REFER_VOLTAGE / CONVERT_BITS;
+ *     rt_kprintf("the voltage is :%d.%02d \n", vol / 100, vol % 100);
+ * 
+ *     rt_thread_mdelay(500);
+ * 
+ *     ret = rt_dac_disable(dac_dev, DAC_DEV_CHANNEL);
+ * 
+ *     return ret;
+ * }
+ * MSH_CMD_EXPORT(dac_vol_sample, dac voltage convert sample);
+ * 
+ * @endcode
+ * 
+ * @ingroup Drivers
+ */
 
+/*!
+ * @addtogroup DAC
+ * @{
+ */
 struct rt_dac_device;
+/**
+ * @brief Configuration of DAC device
+ */
 struct rt_dac_ops
 {
     rt_err_t (*disabled)(struct rt_dac_device *device, rt_uint32_t channel);
@@ -20,7 +78,10 @@ struct rt_dac_ops
     rt_err_t (*convert)(struct rt_dac_device *device, rt_uint32_t channel, rt_uint32_t *value);
     rt_uint8_t (*get_resolution)(struct rt_dac_device *device);
 };
-
+/**
+ * @brief DAC device structure
+ * 
+ */
 struct rt_dac_device
 {
     struct rt_device parent;
@@ -35,10 +96,36 @@ typedef enum
     RT_DAC_CMD_GET_RESOLUTION = RT_DEVICE_CTRL_BASE(DAC) + 2,
 } rt_dac_cmd_t;
 
+/**
+ * @brief Register a DAC device
+ * @param dac DAC device
+ * @param name DAC name
+ * @param ops the operations of DAC device
+ * @param user_data device private data
+ * @return rt_err_t  error code
+ */
 rt_err_t rt_hw_dac_register(rt_dac_device_t dac,const char *name, const struct rt_dac_ops *ops, const void *user_data);
 
+/**
+ * @brief set the value of DAC
+ * @param dev DAC device
+ * @param channel DAC channel
+ * @return rt_err_t  error code
+ */
 rt_err_t rt_dac_write(rt_dac_device_t dev, rt_uint32_t channel, rt_uint32_t value);
+
+/**
+ * @brief enable the DAC channel
+ * @param dev DAC device
+ * @return rt_err_t  error code
+ */
 rt_err_t rt_dac_enable(rt_dac_device_t dev, rt_uint32_t channel);
+
+/**
+ * @brief disable the DAC channel
+ * @param dev DAC device
+ * @return rt_err_t  error code
+ */
 rt_err_t rt_dac_disable(rt_dac_device_t dev, rt_uint32_t channel);
 
 #endif /* __dac_H__ */