From d4ff7616f952bc801390e46bb3163b63cc01828d Mon Sep 17 00:00:00 2001
From: Andres Vahter <andres@vahter.me>
Date: Tue, 2 Jul 2024 17:35:15 +0300
Subject: [PATCH] stm32 ringbuffered adc docs improvements

---
 embassy-stm32/src/adc/ringbuffered_v2.rs | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/embassy-stm32/src/adc/ringbuffered_v2.rs b/embassy-stm32/src/adc/ringbuffered_v2.rs
index 3f5277a9d..8df224783 100644
--- a/embassy-stm32/src/adc/ringbuffered_v2.rs
+++ b/embassy-stm32/src/adc/ringbuffered_v2.rs
@@ -93,11 +93,12 @@ pub struct RingBufferedAdc<'d, T: Instance> {
 impl<'d, T: Instance> Adc<'d, T> {
     /// Configures the ADC to use a DMA ring buffer for continuous data acquisition.
     ///
-    /// The `dma_buf` should be large enough to prevent buffer overflow, allowing sufficient time to read out measurements.
+    /// The `dma_buf` should be large enough to prevent DMA buffer overrun.
     /// The length of the `dma_buf` should be a multiple of the ADC channel count.
     /// For example, if 3 channels are measured, its length can be 3 * 40 = 120 measurements.
     ///
     /// `read_exact` method is used to read out measurements from the DMA ring buffer, and its buffer should be exactly half of the `dma_buf` length.
+    /// It is critical to call `read_exact` frequently to prevent DMA buffer overrun.
     ///
     /// [`read_exact`]: #method.read_exact
     pub fn into_ring_buffered(
@@ -358,18 +359,17 @@ impl<'d, T: Instance> RingBufferedAdc<'d, T> {
 
     /// Reads measurements from the DMA ring buffer.
     ///
-    /// This method fills the provided `measurements` array with ADC readings.
-    /// The length of the `measurements` array should be exactly half of the DMA buffer length.
-    /// Because interrupts are only generated if half or full DMA transfer completes.
+    /// This method fills the provided `measurements` array with ADC readings from the DMA buffer.
+    /// The length of the `measurements` array should be exactly half of the DMA buffer length. Because interrupts are only generated if half or full DMA transfer completes.
     ///
     /// Each call to `read_exact` will populate the `measurements` array in the same order as the channels defined with `set_sample_sequence`.
     /// There will be many sequences worth of measurements in this array because it only returns if at least half of the DMA buffer is filled.
     /// For example if 3 channels are sampled `measurements` contain: `[sq0 sq1 sq3 sq0 sq1 sq3 sq0 sq1 sq3 sq0 sq1 sq3..]`.
     ///
-    /// If an error is returned, it indicates a DMA overrun, and the process must be restarted by calling `start` again.
+    /// If an error is returned, it indicates a DMA overrun, and the process must be restarted by calling `start` or `read_exact` again.
     ///
     /// By default, the ADC fills the DMA buffer as quickly as possible. To control the sample rate, call `teardown_adc` after each readout, and then start the DMA again at the desired interval.
-    /// Note that even if using `teardown_adc` to control sample rate, with each call to `read_exact`, measurements equivalent to half the size of the DMA buffer are still collected.
+    /// Note that even if using `teardown_adc` to control the sample rate, with each call to `read_exact`, measurements equivalent to half the size of the DMA buffer are still collected.
     ///
     /// Example:
     /// ```rust,ignore
@@ -381,7 +381,6 @@ impl<'d, T: Instance> RingBufferedAdc<'d, T> {
     /// adc.set_sample_sequence(Sequence::Two, &mut p.PA1, SampleTime::CYCLES112);
     /// adc.set_sample_sequence(Sequence::Three, &mut p.PA2, SampleTime::CYCLES112);
     ///
-    /// adc.start.unwrap();
     /// let mut measurements = [0u16; DMA_BUF_LEN / 2];
     /// loop {
     ///     match adc.read_exact(&mut measurements).await {
@@ -392,14 +391,12 @@ impl<'d, T: Instance> RingBufferedAdc<'d, T> {
     ///         }
     ///         Err(e) => {
     ///             defmt::warn!("Error: {:?}", e);
-    ///             // DMA overflow, restart ADC.
-    ///             let _ = adc.start();
+    ///             // DMA overrun, next call to `read_exact` restart ADC.
     ///         }
     ///     }
     ///
     ///     // Manually control sample rate.
     ///     Timer::after_millis(100).await;
-    ///     let _ = adc.start();
     /// }
     /// ```
     ///