[doxygen]add rtc devices example for doxygen

3 files changed, 118 insertions, 2 deletions

diff --git a/components/drivers/include/drivers/adc.h b/components/drivers/include/drivers/adc.h
index e285c0a8c2..cdb7b2704a 100644
--- a/components/drivers/include/drivers/adc.h
+++ b/components/drivers/include/drivers/adc.h
@@ -145,4 +145,6 @@ rt_err_t rt_adc_disable(rt_adc_device_t dev, rt_int8_t channel);
  */
 rt_int16_t rt_adc_voltage(rt_adc_device_t dev, rt_int8_t channel);
 
+/*! @}*/
+
 #endif /* __ADC_H__ */
diff --git a/components/drivers/include/drivers/dac.h b/components/drivers/include/drivers/dac.h
index d7160dd936..ca827c7cda 100644
--- a/components/drivers/include/drivers/dac.h
+++ b/components/drivers/include/drivers/dac.h
@@ -128,4 +128,6 @@ rt_err_t rt_dac_enable(rt_dac_device_t dev, rt_uint32_t channel);
  */
 rt_err_t rt_dac_disable(rt_dac_device_t dev, rt_uint32_t channel);
 
+/*! @}*/
+
 #endif /* __dac_H__ */
diff --git a/components/drivers/include/drivers/dev_rtc.h b/components/drivers/include/drivers/dev_rtc.h
index 96658968e5..740142d3d7 100644
--- a/components/drivers/include/drivers/dev_rtc.h
+++ b/components/drivers/include/drivers/dev_rtc.h
@@ -16,7 +16,70 @@
 
 #include <rtdef.h>
 #include <sys/time.h>
+/**
+ * @addtogroup  Drivers    RTTHREAD Driver
+ * @defgroup    RTC        RTC 
+ *
+ * @brief       RTC driver api
+ * 
+ * <b>Example</b>
+ * @code {.c}
+ * 
+ * #include <rtthread.h>
+ * #include <rtdevice.h>
+ * 
+ * #define RTC_NAME       "rtc"
+ * 
+ * static int rtc_sample(int argc, char *argv[])
+ * {
+ *     rt_err_t ret = RT_EOK;
+ *     time_t now;
+ *     rt_device_t device = RT_NULL;
+ * 
+ *     device = rt_device_find(RTC_NAME);
+ *     if (!device)
+ *     {
+ *       LOG_E("find %s failed!", RTC_NAME);
+ *       return RT_ERROR;
+ *     }
+ * 
+ *     if(rt_device_open(device, 0) != RT_EOK)
+ *     {
+ *       LOG_E("open %s failed!", RTC_NAME);
+ *       return RT_ERROR;
+ *     }
+ * 
+ *     ret = set_date(2018, 12, 3);
+ *     if (ret != RT_EOK)
+ *     {
+ *         rt_kprintf("set RTC date failed\n");
+ *         return ret;
+ *     }
+ * 
+ *     ret = set_time(11, 15, 50);
+ *     if (ret != RT_EOK)
+ *     {
+ *         rt_kprintf("set RTC time failed\n");
+ *         return ret;
+ *     }
+ * 
+ *     rt_thread_mdelay(3000);
+ * 
+ *     now = time(RT_NULL);
+ *     rt_kprintf("%s\n", ctime(&now));
+ * 
+ *     return ret;
+ * }
+ * MSH_CMD_EXPORT(rtc_sample, rtc sample);
+ * @endcode
+ * 
+ * @ingroup     Drivers
+ */
 
+/*!
+ * @addtogroup RTC
+ * @{
+ */
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -31,7 +94,9 @@ extern "C" {
 #define RT_DEVICE_CTRL_RTC_SET_TIMESPEC (RT_DEVICE_CTRL_BASE(RTC) + 0x08)              /**< set timespec for clock_settime */
 #define RT_DEVICE_CTRL_RTC_GET_TIMERES  (RT_DEVICE_CTRL_BASE(RTC) + 0x09)              /**< get resolution for clock_getres */
 
-/* used for alarm function */
+/**
+ * @brief RTC alarm structure
+ */
 struct rt_rtc_wkalarm
 {
     rt_bool_t  enable;               /* 0 = alarm disabled, 1 = alarm enabled */
@@ -42,7 +107,9 @@ struct rt_rtc_wkalarm
     rt_int32_t tm_mon;               /* alarm at tm_mon */
     rt_int32_t tm_year;              /* alarm at tm_year */
 };
-
+/**
+ * @brief RTC operations
+ */
 struct rt_rtc_ops
 {
     rt_err_t (*init)(void);
@@ -54,20 +121,63 @@ struct rt_rtc_ops
     rt_err_t (*set_timeval)(struct timeval *tv);
 };
 
+/**
+ * @brief RTC device structure
+ */
 typedef struct rt_rtc_device
 {
     struct rt_device parent;
     const struct rt_rtc_ops *ops;
 } rt_rtc_dev_t;
 
+/**
+ * @brief Register a RTC device
+ * 
+ * @param rtc RTC device
+ * @param name RTC device name
+ * @param flag RTC device flag
+ * @param data RTC device data
+ * @return rt_err_t error code
+ */
 rt_err_t rt_hw_rtc_register(rt_rtc_dev_t  *rtc,
                             const char    *name,
                             rt_uint32_t    flag,
                             void          *data);
 
+/**
+ * @brief set date 
+ * 
+ * @param year year
+ * @param month month
+ * @param day day
+ * @return rt_err_t error code
+ */
 rt_err_t set_date(rt_uint32_t year, rt_uint32_t month, rt_uint32_t day);
+
+/**
+ * @brief set time
+ * 
+ * @param hour hour
+ * @param minute minute
+ * @param second second
+ * @return rt_err_t error code
+*/
 rt_err_t set_time(rt_uint32_t hour, rt_uint32_t minute, rt_uint32_t second);
+
+/**
+ * @brief set timestamp
+ * 
+ * @param timestamp A pointer to time
+ * @return rt_err_t error code
+ */
 rt_err_t set_timestamp(time_t timestamp);
+
+/**
+ * @brief get timestamp
+ * 
+ * @param timestamp A secondary pointer to time
+ * @return rt_err_t error code
+ */
 rt_err_t get_timestamp(time_t *timestamp);
 
 #ifdef RT_USING_SYSTEM_WORKQUEUE
@@ -79,4 +189,6 @@ rt_err_t rt_soft_rtc_set_source(const char *name);
 }
 #endif
 
+/*! @}*/
+
 #endif /* __DEV_RTC_H__ */