docs(terminal): document buffer diffing better (#852)

src/lib.rs

@@ -86,7 +86,8 @@
 //!
 //! The drawing logic is delegated to a closure that takes a [`Frame`] instance as argument. The
 //! [`Frame`] provides the size of the area to draw to and allows the app to render any [`Widget`]
-//! using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Website]
+//! using the provided [`render_widget`] method. After this closure returns, a diff is performed and
+//! only the changes are drawn to the terminal. See the [Widgets] section of the [Ratatui Website]
 //! for more info.
 //!
 //! ### Handling events

src/terminal/frame.rs

@@ -8,9 +8,9 @@ use crate::{
 /// This is obtained via the closure argument of [`Terminal::draw`]. It is used to render widgets
 /// to the terminal and control the cursor position.
 ///
-/// The changes drawn to the frame are applied only to the current [`Buffer`].
+/// The changes drawn to the frame are applied only to the current [`Buffer`]. After the closure
-/// After the closure returns, the current buffer is compared to the previous
+/// returns, the current buffer is compared to the previous buffer and only the changes are applied
-/// buffer and only the changes are applied to the terminal.
+/// to the terminal. This avoids drawing redundant cells.
 ///
 /// [`Buffer`]: crate::buffer::Buffer
 #[derive(Debug, Hash)]

src/terminal/terminal.rs

@@ -16,7 +16,7 @@ use crate::{backend::ClearType, prelude::*};
 /// When the widgets are drawn, the changes are accumulated in the current buffer.
 /// At the end of each draw pass, the two buffers are compared, and only the changes
 /// between these buffers are written to the terminal, avoiding any redundant operations.
-/// After flushing these changes, the buffers are swapped to prepare for the next draw cycle./
+/// After flushing these changes, the buffers are swapped to prepare for the next draw cycle.
 ///
 /// The terminal also has a viewport which is the area of the terminal that is currently visible to
 /// the user. It can be either fullscreen, inline or fixed. See [`Viewport`] for more information.
@@ -239,6 +239,10 @@ where
     ///
     /// This is the main entry point for drawing to the terminal.
     ///
+    /// The changes drawn to the frame are applied only to the current [`Buffer`]. After the closure
+    /// returns, the current buffer is compared to the previous buffer and only the changes are
+    /// applied to the terminal.
+    ///
     /// # Examples
     ///
     /// ```rust,no_run