driver/rtc_io: improve header comments

Fix descriptions of return values, fix typos, use upper case for abbreviations.

diff --git a/components/driver/include/driver/rtc_io.h b/components/driver/include/driver/rtc_io.h
index 5196b058a5421a2d2fd5a6b04642d9ea4cc33493..2e351cf13aa88024fe5713e762deac2570cf1ed3 100644 (file)
--- a/components/driver/include/driver/rtc_io.h
+++ b/components/driver/include/driver/rtc_io.h
@@ -27,136 +27,142 @@ extern "C" {
  * @brief Pullup/pulldown information for a single GPIO pad
  */
 typedef struct {
-    uint32_t reg;       /*!< Register of Rtc Pad */
-    uint32_t mux;       /*!< Mux seletct the Rtc pad is Digital Pad or Rtc pad */
-    uint32_t func;      /*!< Select Rtc Pad Func */
-    uint32_t ie;        /*!< Input Enable */
-    uint32_t pullup;    /*!< Pullup Enable */
-    uint32_t pulldown;  /*!< PullDown Enable */
-    int rtc_num;        /*!< The Rtc number */
+    uint32_t reg;       /*!< Register of RTC pad, or 0 if not an RTC GPIO */
+    uint32_t mux;       /*!< Bit mask for selecting digital pad or RTC pad */
+    uint32_t func;      /*!< Mask of RTC pad function */
+    uint32_t ie;        /*!< Mask of input enable */
+    uint32_t pullup;    /*!< Mask of pullup enable */
+    uint32_t pulldown;  /*!< Mask of pulldown enable */
+    int rtc_num;        /*!< RTC IO number, or -1 if not an RTC GPIO */
 } rtc_gpio_desc_t;
 
 typedef enum {
-    RTC_GPIO_MODE_INPUT_ONLY , /*!< Pad output           */
-    RTC_GPIO_MODE_OUTPUT_ONLY, /*!< Pad input          */
-    RTC_GPIO_MODE_INPUT_OUTUT, /*!< Pad pull output + input      */
-    RTC_GPIO_MODE_DISABLED, /*!< Pad (output + input) disable       */
+    RTC_GPIO_MODE_INPUT_ONLY , /*!< Pad output */
+    RTC_GPIO_MODE_OUTPUT_ONLY, /*!< Pad input */
+    RTC_GPIO_MODE_INPUT_OUTUT, /*!< Pad pull output + input */
+    RTC_GPIO_MODE_DISABLED,    /*!< Pad (output + input) disable */
 } rtc_gpio_mode_t;
 
 #define RTC_GPIO_IS_VALID_GPIO(gpio_num)      ((gpio_num < GPIO_PIN_COUNT && rtc_gpio_desc[gpio_num].reg != 0))   //to decide whether it is a valid GPIO number
 
-extern const rtc_gpio_desc_t rtc_gpio_desc[GPIO_PIN_COUNT] ;
+extern const rtc_gpio_desc_t rtc_gpio_desc[GPIO_PIN_COUNT];
 
-/*
- * @brief Init a gpio as rtc gpio
+/**
+ * @brief Init a GPIO as RTC GPIO
  *
- *        when init a pad as analog function,need to call this funciton
+ * This function must be called when initializing a pad for an analog function.
  *
- * @param  gpio_num gpio_num GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_12 (12);
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
  *
  * @return
  *     - ESP_OK success
- *     - ESP_ERR_INVALID_ARG Parameter error
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 esp_err_t rtc_gpio_init(gpio_num_t gpio_num);
 
 /**
- * @brief Init a gpio as digital gpio
+ * @brief Init a GPIO as digital GPIO
  *
- * @param  gpio_num gpio_num GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_12 (12);
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
  *
  * @return
  *     - ESP_OK success
- *     - ESP_ERR_INVALID_ARG Parameter error
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 esp_err_t rtc_gpio_deinit(gpio_num_t gpio_num);
 
 /**
- * @brief Get the rtc io input level
+ * @brief Get the RTC IO input level
  *
- * @param  gpio_num gpio_num GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_12 (12);
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
  *
  * @return
  *     - 1 High level
  *     - 0 Low level
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 uint32_t rtc_gpio_get_level(gpio_num_t gpio_num);
 
 /**
- * @brief Set the rtc io output level
+ * @brief Set the RTC IO output level
  *
- * @param  gpio_num  GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_12 (12);
- * @param  level output level;
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
+ * @param  level output level
  *
  * @return
- *     - 1 High level
- *     - 0 Low level
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 esp_err_t rtc_gpio_set_level(gpio_num_t gpio_num, uint32_t level);
 
 /**
- * @brief    Rtc gpio set direction
+ * @brief    RTC GPIO set direction
  *
- * Configure Rtc gpio direction,such as output_only,input_only,output_and_input
+ * Configure RTC GPIO direction, such as output only, input only,
+ * output and input.
  *
- * @param  gpio_num  Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12);
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
  * @param  mode GPIO direction
  *
  * @return
  *     - ESP_OK Success
- *     - ESP_ERR_INVALID_ARG GPIO error
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 esp_err_t rtc_gpio_set_direction(gpio_num_t gpio_num, rtc_gpio_mode_t mode);
 
 /**
- * @brief  Rtc gpio pullup enable
+ * @brief  RTC GPIO pullup enable
  *
- * If the user needs to configure the GPIO pull ,Please call gpio_set_pull_mode.This function will be called in gpio_set_pull
+ * This function only works for RTC IOs. In general, call gpio_pullup_en,
+ * which will work both for normal GPIOs and RTC IOs.
  *
- * @param  gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12);
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
  *
  * @return
- *     - True  the gpio number is Rts pad
- *     - False the gpio number is Digital pad
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 esp_err_t rtc_gpio_pullup_en(gpio_num_t gpio_num);
 
 /**
- * @brief  Rtc gpio pulldown enable
+ * @brief  RTC GPIO pulldown enable
  *
- * If the user needs to configure the GPIO pull ,Please call gpio_set_pull_mode.This function will be called in gpio_set_pull
+ * This function only works for RTC IOs. In general, call gpio_pulldown_en,
+ * which will work both for normal GPIOs and RTC IOs.
  *
- * @param  gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12);
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
  *
  * @return
- *     - True  the gpio number is Rts pad
- *     - False the gpio number is Digital pad
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 esp_err_t rtc_gpio_pulldown_en(gpio_num_t gpio_num);
 
 /**
- * @brief  Rtc gpio pullup clear
+ * @brief  RTC GPIO pullup disable
  *
- * If the user needs to configure the GPIO pull ,Please call gpio_set_pull_mode.This function will be called in gpio_set_pull
+ * This function only works for RTC IOs. In general, call gpio_pullup_dis,
+ * which will work both for normal GPIOs and RTC IOs.
  *
- * @param  gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12);
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
  *
  * @return
- *     - True  the gpio number is Rts pad
- *     - False the gpio number is Digital pad
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 esp_err_t rtc_gpio_pullup_dis(gpio_num_t gpio_num);
 
 /**
- * @brief  Rtc gpio pulldown clear
+ * @brief  RTC GPIO pulldown disable
  *
- * If the user needs to configure the GPIO pull ,Please call gpio_set_pull_mode.This function will be called in gpio_set_pull
+ * This function only works for RTC IOs. In general, call gpio_pulldown_dis,
+ * which will work both for normal GPIOs and RTC IOs.
  *
- * @param  gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12);
+ * @param  gpio_num GPIO number (e.g. GPIO_NUM_12)
  *
  * @return
- *     - True  the gpio number is Rts pad
- *     - False the gpio number is Digital pad
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
  */
 esp_err_t rtc_gpio_pulldown_dis(gpio_num_t gpio_num);