adc: Add doc details about configure not needed before each read

diff --git a/components/driver/include/driver/adc.h b/components/driver/include/driver/adc.h
index ccbe85014e15c191d413fb199cde1b3e5660fa27..e6c6df1a403e2ff1263ed58de82a4f80eb6e8bc9 100644 (file)
--- a/components/driver/include/driver/adc.h
+++ b/components/driver/include/driver/adc.h
@@ -147,11 +147,15 @@ esp_err_t adc1_config_width(adc_bits_width_t width_bit);
 esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit);
 
 /**
- * @brief Configure the ADC1 channel, including setting attenuation.
+ * @brief Set the attenuation of a particular channel on ADC1, and configure its
+ * associated GPIO pin mux.
  *
- * @note This function also configures the input GPIO pin mux to
- * connect it to the ADC1 channel. It must be called before calling
- * adc1_get_raw() for this channel.
+ * @note For any given channel, this function must be called before the first time
+ * adc1_get_raw() is called for that channel.
+ *
+ * @note This function can be called multiple times to configure multiple
+ * ADC channels simultaneously. adc1_get_raw() can then be called for any configured
+ * channel.
  *
  * The default ADC full-scale voltage is 1.1V. To read higher voltages (up to the pin maximum voltage,
  * usually 3.3V) requires setting >0dB signal attenuation for that ADC channel.
@@ -168,6 +172,15 @@ esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit);
  *
  * @note At 11dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage.
  *
+ * Due to ADC characteristics, most accurate results are obtained within the following approximate voltage ranges:
+ *
+ * - 0dB attenuaton (ADC_ATTEN_DB_0) between 100 and 950mV
+ * - 2.5dB attenuation (ADC_ATTEN_DB_2_5) between 100 and 1250mV
+ * - 6dB attenuation (ADC_ATTEN_DB_6) between 150 to 1750mV
+ * - 11dB attenuation (ADC_ATTEN_DB_11) between 150 to 2450mV
+ *
+ * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.
+ *
  * @param channel ADC1 channel to configure
  * @param atten  Attenuation level
  *
@@ -178,13 +191,14 @@ esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit);
 esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten);
 
 /**
- * @brief Take an ADC1 reading on a single channel
+ * @brief Take an ADC1 reading from a single channel.
  *
  * @note Call adc1_config_width() before the first time this
  * function is called.
  *
- * @note For a given channel, adc1_config_channel_atten(channel)
- * must be called before the first time this function is called.
+ * @note For any given channel, adc1_config_channel_atten(channel)
+ * must be called before the first time this function is called. Configuring
+ * a new channel does not prevent a previously configured channel from being read.
  *
  * @param  channel ADC1 channel to read
  *