docs(terminal): Made usage of Terminal::get_frame() clearer (#2071)

Closes : https://github.com/ratatui/ratatui/issues/1200

---------

Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
Co-authored-by: Orhun Parmaksız <orhun@archlinux.org>

ratatui-core/src/layout/layout.rs

@@ -130,7 +130,7 @@ impl From<i16> for Spacing {
 ///
 /// When the layout is computed, the result is cached in a thread-local cache, so that subsequent
 /// calls with the same parameters are faster. The cache is a `LruCache`, and the size of the cache
-/// can be configured using [`Layout::init_cache()`].
+/// can be configured using [`Layout::init_cache()`] when the `layout-cache` feature is enabled.
 ///
 /// # Construction
 ///
@@ -203,8 +203,8 @@ impl Layout {
     /// on my laptop's terminal (171+51 = 222) and doubling it for good measure and then adding a
     /// bit more to make it a round number. This gives enough entries to store a layout for every
     /// row and every column, twice over, which should be enough for most apps. For those that need
-    /// more, the cache size can be set with [`Layout::init_cache()`].
-    /// This const is unused if layout cache is disabled.
+    /// more, the cache size can be set with `Layout::init_cache()` (requires the `layout-cache`
+    /// feature).
     #[cfg(feature = "layout-cache")]
     pub const DEFAULT_CACHE_SIZE: usize = 500;
 
@@ -636,8 +636,8 @@ impl Layout {
     ///
     /// This method stores the result of the computation in a thread-local cache keyed on the layout
     /// and area, so that subsequent calls with the same parameters are faster. The cache is a
-    /// `LruCache`, and grows until [`Self::DEFAULT_CACHE_SIZE`] is reached by default, if the cache
-    /// is initialized with the [`Layout::init_cache()`] grows until the initialized cache size.
+    /// `LruCache`, and grows until [`Self::DEFAULT_CACHE_SIZE`] is reached by default. If the cache
+    /// is initialized with [`Layout::init_cache()`], it grows until the initialized cache size.
     ///
     /// There is a helper method that can be used to split the whole area into smaller ones based on
     /// the layout: [`Layout::areas()`]. That method is a shortcut for calling this method. It
@@ -673,8 +673,8 @@ impl Layout {
     ///
     /// This method stores the result of the computation in a thread-local cache keyed on the layout
     /// and area, so that subsequent calls with the same parameters are faster. The cache is a
-    /// `LruCache`, and grows until [`Self::DEFAULT_CACHE_SIZE`] is reached by default, if the cache
-    /// is initialized with the [`Layout::init_cache()`] grows until the initialized cache size.
+    /// `LruCache`, and grows until [`Self::DEFAULT_CACHE_SIZE`] is reached by default. If the cache
+    /// is initialized with [`Layout::init_cache()`], it grows until the initialized cache size.
     ///
     /// # Examples
     ///

ratatui-core/src/terminal/terminal.rs

@@ -203,6 +203,40 @@ where
     }
 
     /// Get a Frame object which provides a consistent view into the terminal state for rendering.
+    ///
+    /// # Note
+    ///
+    /// This exists to support more advanced use cases. Most cases should be fine using
+    /// [`Terminal::draw`].
+    ///
+    /// [`Terminal::get_frame`] should be used when you need direct access to the frame buffer
+    /// outside of draw closure, for example:
+    ///
+    /// - Unit testing widgets
+    /// - Buffer state inspection
+    /// - Cursor manipulation
+    /// - Multiple rendering passes/Buffer Manipulation
+    /// - Custom frame lifecycle management
+    /// - Buffer exporting
+    ///
+    /// # Example
+    ///
+    /// Getting the buffer and asserting on some cells after rendering a widget.
+    ///
+    /// ```rust,ignore
+    /// use ratatui::{backend::TestBackend, Terminal};
+    /// use ratatui::widgets::Paragraph;
+    /// let backend = TestBackend::new(30, 5);
+    /// let mut terminal = Terminal::new(backend).unwrap();
+    /// {
+    ///     let mut frame = terminal.get_frame();
+    ///     frame.render_widget(Paragraph::new("Hello"), frame.area());
+    /// }
+    /// // When not using `draw`, present the buffer manually:
+    /// terminal.flush().unwrap();
+    /// terminal.swap_buffers();
+    /// terminal.backend_mut().flush().unwrap();
+    /// ```
     pub const fn get_frame(&mut self) -> Frame<'_> {
         let count = self.frame_count;
         Frame {