fix: make deprecation notes more helpful (#1702)

AI coding assistants use the deprecation notes to automatically suggest
fixes. This commit updates the deprecation notes to push those tools to
suggest the correct replacement methods and types.

Specifically, AI tools often suggest using `Buffer::get(x, y)`, because
of their training data where this was prevalent. When fixing these
deprecations, they often incorrectly suggest using `Buffer::get(x, y)`
instead of `Buffer[(x, y)]`.

ratatui-core/src/backend.rs

@@ -223,7 +223,7 @@ pub trait Backend {
     ///
     /// The returned tuple contains the x and y coordinates of the cursor. The origin
     /// (0, 0) is at the top left corner of the screen.
-    #[deprecated = "the method get_cursor_position indicates more clearly what about the cursor to get"]
+    #[deprecated = "use `get_cursor_position()` instead which returns `Result<Position>`"]
     fn get_cursor(&mut self) -> io::Result<(u16, u16)> {
         let Position { x, y } = self.get_cursor_position()?;
         Ok((x, y))
@@ -232,7 +232,7 @@ pub trait Backend {
     /// Set the cursor position on the terminal screen to the given x and y coordinates.
     ///
     /// The origin (0, 0) is at the top left corner of the screen.
-    #[deprecated = "the method set_cursor_position indicates more clearly what about the cursor to set"]
+    #[deprecated = "use `set_cursor_position((x, y))` instead which takes `impl Into<Position>`"]
     fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()> {
         self.set_cursor_position(Position { x, y })
     }

ratatui-core/src/buffer/assert.rs

@@ -3,7 +3,7 @@
 /// # Panics
 /// When the buffers differ this method panics and displays the differences similar to
 /// `assert_eq!()`.
-#[deprecated = "use assert_eq!(&actual, &expected)"]
+#[deprecated = "use `assert_eq!(&actual, &expected)`"]
 #[macro_export]
 macro_rules! assert_buffer_eq {
     ($actual_expr:expr, $expected_expr:expr) => {

ratatui-core/src/buffer/buffer.rs

@@ -129,7 +129,7 @@ impl Buffer {
     ///
     /// Panics if the index is out of bounds.
     #[track_caller]
-    #[deprecated(note = "Use Buffer[] or Buffer::cell instead")]
+    #[deprecated = "use `Buffer[(x, y)]` instead. To avoid panicking, use `Buffer::cell((x, y))`. Both methods take `impl Into<Position>`."]
     #[must_use]
     pub fn get(&self, x: u16, y: u16) -> &Cell {
         let i = self.index_of(x, y);
@@ -149,7 +149,7 @@ impl Buffer {
     ///
     /// Panics if the position is outside the `Buffer`'s area.
     #[track_caller]
-    #[deprecated(note = "Use Buffer[] or Buffer::cell_mut instead")]
+    #[deprecated = "use `Buffer[(x, y)]` instead. To avoid panicking, use `Buffer::cell_mut((x, y))`. Both methods take `impl Into<Position>`."]
     #[must_use]
     pub fn get_mut(&mut self, x: u16, y: u16) -> &mut Cell {
         let i = self.index_of(x, y);

ratatui-core/src/terminal/frame.rs

@@ -67,7 +67,7 @@ impl Frame<'_> {
     /// If your app listens for a resize event from the backend, it should ignore the values from
     /// the event for any calculations that are used to render the current frame and use this value
     /// instead as this is the area of the buffer that is used to render the current frame.
-    #[deprecated = "use .area() as it's the more correct name"]
+    #[deprecated = "use `area()` instead"]
     pub const fn size(&self) -> Rect {
         self.viewport_area
     }
@@ -154,7 +154,7 @@ impl Frame<'_> {
     /// [`Terminal::hide_cursor`]: crate::terminal::Terminal::hide_cursor
     /// [`Terminal::show_cursor`]: crate::terminal::Terminal::show_cursor
     /// [`Terminal::set_cursor_position`]: crate::terminal::Terminal::set_cursor_position
-    #[deprecated = "the method set_cursor_position indicates more clearly what about the cursor to set"]
+    #[deprecated = "use `set_cursor_position((x, y))` instead which takes `impl Into<Position>`"]
     pub fn set_cursor(&mut self, x: u16, y: u16) {
         self.set_cursor_position(Position { x, y });
     }

ratatui-core/src/terminal/terminal.rs

@@ -440,14 +440,14 @@ where
     ///
     /// This is the position of the cursor after the last draw call and is returned as a tuple of
     /// `(x, y)` coordinates.
-    #[deprecated = "the method get_cursor_position indicates more clearly what about the cursor to get"]
+    #[deprecated = "use `get_cursor_position()` instead which returns `Result<Position>`"]
     pub fn get_cursor(&mut self) -> io::Result<(u16, u16)> {
         let Position { x, y } = self.get_cursor_position()?;
         Ok((x, y))
     }
 
     /// Sets the cursor position.
-    #[deprecated = "the method set_cursor_position indicates more clearly what about the cursor to set"]
+    #[deprecated = "use `set_cursor_position((x, y))` instead which takes `impl Into<Position>`"]
     pub fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()> {
         self.set_cursor_position(Position { x, y })
     }

ratatui-core/src/text/span.rs

@@ -341,7 +341,7 @@ impl<'a> Span<'a> {
     }
 
     #[allow(clippy::wrong_self_convention)]
-    #[deprecated = "use into_left_aligned_line"]
+    #[deprecated = "use `into_left_aligned_line()` instead"]
     pub fn to_left_aligned_line(self) -> Line<'a> {
         self.into_left_aligned_line()
     }
@@ -361,7 +361,7 @@ impl<'a> Span<'a> {
     }
 
     #[allow(clippy::wrong_self_convention)]
-    #[deprecated = "use into_centered_line"]
+    #[deprecated = "use `into_centered_line()` instead"]
     pub fn to_centered_line(self) -> Line<'a> {
         self.into_centered_line()
     }
@@ -381,7 +381,7 @@ impl<'a> Span<'a> {
     }
 
     #[allow(clippy::wrong_self_convention)]
-    #[deprecated = "use into_right_aligned_line"]
+    #[deprecated = "use `into_right_aligned_line()` instead"]
     pub fn to_right_aligned_line(self) -> Line<'a> {
         self.into_right_aligned_line()
     }

ratatui-widgets/src/block.rs

@@ -4,6 +4,7 @@
 //!
 //! In its simplest form, a `Block` is a [border](Borders) around another widget. It can have a
 //! [title](Block::title) and [padding](Block::padding).
+#![allow(deprecated)] // to avoid having to add `#[deprecated]` to every use of `Title`
 
 use itertools::Itertools;
 use ratatui_core::{

ratatui-widgets/src/block/padding.rs

@@ -56,7 +56,7 @@ impl Padding {
     }
 
     /// Creates a `Padding` with all fields set to `0`.
-    #[deprecated = "use Padding::ZERO"]
+    #[deprecated = "use `Padding::ZERO` instead"]
     pub const fn zero() -> Self {
         Self::ZERO
     }

ratatui-widgets/src/block/title.rs

@@ -57,6 +57,7 @@ use strum::{Display, EnumString};
 ///     .alignment(Alignment::Right);
 /// ```
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
+#[deprecated = "use `title_top()` or `title_bottom()` instead"]
 pub struct Title<'a> {
     /// Title content
     pub content: Line<'a>,
@@ -101,7 +102,6 @@ pub enum Position {
     Bottom,
 }
 
-#[deprecated = "use Block::title_top() or Block::title_bottom() instead. This will be removed in a future release."]
 impl<'a> Title<'a> {
     /// Set the title content.
     #[must_use = "method moves the value of self and returns the modified value"]

ratatui-widgets/src/gauge.rs

@@ -330,7 +330,7 @@ impl<'a> LineGauge<'a> {
     #[must_use = "method moves the value of self and returns the modified value"]
     #[deprecated(
         since = "0.30.0",
-        note = "You should use `LineGauge::filled_symbol` and `LineGauge::unfilled_symbol` instead."
+        note = "use `filled_symbol()` and `unfilled_symbol()` instead"
     )]
     pub const fn line_set(mut self, set: symbols::line::Set) -> Self {
         self.filled_symbol = set.horizontal;
@@ -382,10 +382,7 @@ impl<'a> LineGauge<'a> {
     ///
     /// `style` accepts any type that is convertible to [`Style`] (e.g. [`Style`], [`Color`], or
     /// your own type that implements [`Into<Style>`]).
-    #[deprecated(
-        since = "0.27.0",
-        note = "You should use `LineGauge::filled_style` instead."
-    )]
+    #[deprecated(since = "0.27.0", note = "use `filled_style()` instead")]
     #[must_use = "method moves the value of self and returns the modified value"]
     pub fn gauge_style<S: Into<Style>>(mut self, style: S) -> Self {
         let style: Style = style.into();

ratatui-widgets/src/table.rs

@@ -580,7 +580,7 @@ impl<'a> Table<'a> {
     ///
     /// [`Color`]: ratatui_core::style::Color
     #[must_use = "method moves the value of self and returns the modified value"]
-    #[deprecated(note = "use `Table::row_highlight_style` instead")]
+    #[deprecated(note = "use `row_highlight_style()` instead")]
     pub fn highlight_style<S: Into<Style>>(self, highlight_style: S) -> Self {
         self.row_highlight_style(highlight_style)
     }