From f4a92e5e865e28a5c8be13e371722cbae5ae7cea Mon Sep 17 00:00:00 2001
From: CYFS <2805686936@qq.com>
Date: Wed, 25 Sep 2024 22:19:53 +0800
Subject: [PATCH] [doxygen][rsoc] add adc driver example for doxygen (#9465)

* [doxygen] add adc driver example for doxygen

* add data structures
---
 components/drivers/include/drivers/adc.h | 98 +++++++++++++++++++++++-
 1 file changed, 97 insertions(+), 1 deletion(-)

diff --git a/components/drivers/include/drivers/adc.h b/components/drivers/include/drivers/adc.h
index 7c35f1eac6..e285c0a8c2 100644
--- a/components/drivers/include/drivers/adc.h
+++ b/components/drivers/include/drivers/adc.h
@@ -14,12 +14,65 @@
 #define __ADC_H__
 
 #include <rtthread.h>
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    ADC           ADC
+ *
+ * @brief       ADC driver api
+ *
+ * <b>Example</b>
+ * @code {.c}
+ * #define ADC_DEV_NAME        "adc1"      
+ * #define ADC_DEV_CHANNEL     5    
+ * #define REFER_VOLTAGE       330         
+ * #define CONVERT_BITS        (1 << 12)   
+ * 
+ * static int adc_vol_sample(int argc, char *argv[])
+ * {
+ *     rt_adc_device_t adc_dev;
+ *     rt_uint32_t value, vol;
+ * 
+ *     rt_err_t ret = RT_EOK;
+ * 
+ *     adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME);
+ *     if (adc_dev == RT_NULL)
+ *     {
+ *         rt_kprintf("adc sample run failed! can't find %s device!\n", ADC_DEV_NAME);
+ *         return RT_ERROR;
+ *     }
+ * 
+ *     ret = rt_adc_enable(adc_dev, ADC_DEV_CHANNEL);
+ * 
+ *     value = rt_adc_read(adc_dev, ADC_DEV_CHANNEL);
+ *     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);
+ * 
+ *     ret = rt_adc_disable(adc_dev, ADC_DEV_CHANNEL);
+ * 
+ *     return ret;
+ * }
+ * MSH_CMD_EXPORT(adc_vol_sample, adc voltage convert sample);
+ *       
+ * @endcode
+ *
+ * @ingroup     Drivers
+ */
 
+
+/*!
+ * @addtogroup ADC
+ * @{
+ */
 #define RT_ADC_INTERN_CH_TEMPER     (-1)
 #define RT_ADC_INTERN_CH_VREF       (-2)
 #define RT_ADC_INTERN_CH_VBAT       (-3)
 
 struct rt_adc_device;
+/**
+ * @brief Configure the adc device
+ */
 struct rt_adc_ops
 {
     rt_err_t (*enabled)(struct rt_adc_device *device, rt_int8_t channel, rt_bool_t enabled);
@@ -27,7 +80,9 @@ struct rt_adc_ops
     rt_uint8_t (*get_resolution)(struct rt_adc_device *device);
     rt_int16_t (*get_vref) (struct rt_adc_device *device);
 };
-
+/**
+ * @brief adc device
+ */
 struct rt_adc_device
 {
     struct rt_device parent;
@@ -43,10 +98,51 @@ typedef enum
     RT_ADC_CMD_GET_VREF = RT_DEVICE_CTRL_BASE(ADC) + 4, /* get reference voltage */
 } rt_adc_cmd_t;
 
+/**
+ * @brief register the adc device
+ * @param adc adc device
+ * @param name device name
+ * @param ops device ops
+ * @param user_data device private data
+ * @return rt_err_t        error code
+ * @ingroup  ADC
+ */
 rt_err_t rt_hw_adc_register(rt_adc_device_t adc,const char *name, const struct rt_adc_ops *ops, const void *user_data);
+
+/**
+ * @brief read the adc value
+ * @param dev adc device
+ * @param channel adc channel
+ * @return rt_uint32_t adc value
+ * @ingroup  ADC
+ */
 rt_uint32_t rt_adc_read(rt_adc_device_t dev, rt_int8_t channel);
+
+/**
+ * @brief enable the adc channel
+ * @param dev adc device
+ * @param channel adc channel
+ * @return rt_err_t error code
+ * @ingroup  ADC
+ */
 rt_err_t rt_adc_enable(rt_adc_device_t dev, rt_int8_t channel);
+
+/**
+ * @brief disable the adc channel
+ * @param dev adc device
+ * @param channel adc channel
+ * @return rt_err_t error code
+ * @ingroup  ADC
+ */
 rt_err_t rt_adc_disable(rt_adc_device_t dev, rt_int8_t channel);
+
+/**
+ * @brief get the adc resolution
+ * @param dev adc device
+ * @param channel adc channel
+ * @return rt_int16_t adc resolution
+ * @ingroup  ADC
+ */
 rt_int16_t rt_adc_voltage(rt_adc_device_t dev, rt_int8_t channel);
 
 #endif /* __ADC_H__ */