doc: improve comment

embassy-stm32/src/dma/ringbuffer/mod.rs

@@ -253,10 +253,17 @@ impl<'a, W: Word> WritableDmaRingBuffer<'a, W> {
 
     /// Write elements directly to the buffer.
     ///
+    /// Subsequent writes will overwrite the content of the buffer, so it is not useful to call this more than once.
     /// Data is aligned towards the end of the buffer.
+    ///
+    /// In case of success, returns the written length, and the empty space in front of the written block.
+    /// Fails if the data to write exceeds the buffer capacity.
     pub fn write_immediate(&mut self, buf: &[W]) -> Result<(usize, usize), Error> {
-        let start = self.cap() - buf.len();
+        if buf.len() > self.cap() {
+            return Err(Error::Overrun);
+        }
 
+        let start = self.cap() - buf.len();
         for (i, data) in buf.iter().enumerate() {
             self.write_buf(start + i, *data)
         }