chore: Correct "builder methods" in docs and add must_use on widgets setters (#655)

Fixes #650

This PR corrects the "builder methods" expressing to simple `setters`
(see #650 #655), and gives a clearer diagnostic notice on setters `must_use`.

`#[must_use = "method moves the value of self and returns the modified value"]`

Details:

    docs: Correct wording in docs from builder methods

    Add `must_use` on layout setters

    chore: add `must_use` on widgets fluent methods

        This commit ignored `table.rs` because it is included in other PRs.

    test(gauge): fix test

src/layout.rs

@@ -350,6 +350,7 @@ impl Layout {
     /// let layout = Layout::default().constraints([Constraint::Min(0)].iter().filter(|_| true));
     /// let layout = Layout::default().constraints([1,2,3].iter().map(|&c| Constraint::Length(c)));
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn constraints<I>(mut self, constraints: I) -> Layout
     where
         I: IntoIterator,
@@ -359,7 +360,7 @@ impl Layout {
         self
     }
 
-    /// Builder method to set the margin of the layout.
+    /// Set the margin of the layout.
     ///
     /// # Examples
     ///
@@ -371,6 +372,7 @@ impl Layout {
     ///     .split(Rect::new(0, 0, 10, 10));
     /// assert_eq!(layout[..], [Rect::new(2, 2, 6, 6)]);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn margin(mut self, margin: u16) -> Layout {
         self.margin = Margin {
             horizontal: margin,
@@ -379,7 +381,7 @@ impl Layout {
         self
     }
 
-    /// Builder method to set the horizontal margin of the layout.
+    /// Set the horizontal margin of the layout.
     ///
     /// # Examples
     ///
@@ -391,12 +393,13 @@ impl Layout {
     ///     .split(Rect::new(0, 0, 10, 10));
     /// assert_eq!(layout[..], [Rect::new(2, 0, 6, 10)]);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn horizontal_margin(mut self, horizontal: u16) -> Layout {
         self.margin.horizontal = horizontal;
         self
     }
 
-    /// Builder method to set the vertical margin of the layout.
+    /// Set the vertical margin of the layout.
     ///
     /// # Examples
     ///
@@ -408,12 +411,13 @@ impl Layout {
     ///     .split(Rect::new(0, 0, 10, 10));
     /// assert_eq!(layout[..], [Rect::new(0, 2, 10, 6)]);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn vertical_margin(mut self, vertical: u16) -> Layout {
         self.margin.vertical = vertical;
         self
     }
 
-    /// Builder method to set the direction of the layout.
+    /// Set the direction of the layout.
     ///
     /// # Examples
     ///
@@ -431,12 +435,13 @@ impl Layout {
     ///     .split(Rect::new(0, 0, 10, 10));
     /// assert_eq!(layout[..], [Rect::new(0, 0, 10, 5), Rect::new(0, 5, 10, 5)]);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn direction(mut self, direction: Direction) -> Layout {
         self.direction = direction;
         self
     }
 
-    /// Builder method to set whether chunks should be of equal size.
+    /// Set whether chunks should be of equal size.
     ///
     /// This determines how the space is distributed when the constraints are satisfied. By default,
     /// the last chunk is expanded to fill the remaining space, but this can be changed to prefer
@@ -452,6 +457,7 @@ impl Layout {
         reason = "The name for this feature is not final and may change in the future",
         issue = "https://github.com/ratatui-org/ratatui/issues/536"
     )]
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn segment_size(mut self, segment_size: SegmentSize) -> Layout {
         self.segment_size = segment_size;
         self

src/title.rs

@@ -87,7 +87,7 @@ pub enum Position {
 }
 
 impl<'a> Title<'a> {
-    /// Builder pattern method for setting the title content.
+    /// Set the title content.
     pub fn content<T>(mut self, content: T) -> Title<'a>
     where
         T: Into<Line<'a>>,
@@ -96,13 +96,15 @@ impl<'a> Title<'a> {
         self
     }
 
-    /// Builder pattern method for setting the title alignment.
+    /// Set the title alignment.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn alignment(mut self, alignment: Alignment) -> Title<'a> {
         self.alignment = Some(alignment);
         self
     }
 
-    /// Builder pattern method for setting the title position.
+    /// Set the title position.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn position(mut self, position: Position) -> Title<'a> {
         self.position = Some(position);
         self

src/widgets.rs

@@ -1,7 +1,7 @@
 //! `widgets` is a collection of types that implement [`Widget`] or [`StatefulWidget`] or both.
 //!
-//! All widgets are implemented using the builder pattern and are consumable objects. They are not
+//! Widgets are created for each frame as they are consumed after rendered.
-//! meant to be stored but used as *commands* to draw common figures in the UI.
+//! They are not meant to be stored but used as *commands* to draw common figures in the UI.
 //!
 //! The available widgets are:
 //! - [`Block`]: a basic widget that draws a block with optional borders, titles and styles.

src/widgets/barchart.rs

@@ -127,6 +127,7 @@ impl<'a> BarChart<'a> {
     }
 
     /// Surround the [`BarChart`] with a [`Block`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> BarChart<'a> {
         self.block = Some(block);
         self
@@ -161,6 +162,7 @@ impl<'a> BarChart<'a> {
     /// // █ █ █
     /// // f b b
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn max(mut self, max: u64) -> BarChart<'a> {
         self.max = Some(max);
         self
@@ -170,6 +172,7 @@ impl<'a> BarChart<'a> {
     ///
     /// It is also possible to set individually the style of each [`Bar`].
     /// In this case the default style will be patched by the individual style
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_style(mut self, style: Style) -> BarChart<'a> {
         self.bar_style = style;
         self
@@ -182,6 +185,7 @@ impl<'a> BarChart<'a> {
     ///
     /// If not set, this defaults to `1`.  
     /// The bar label also uses this value as its width.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_width(mut self, width: u16) -> BarChart<'a> {
         self.bar_width = width;
         self
@@ -205,6 +209,7 @@ impl<'a> BarChart<'a> {
     /// // █   █
     /// // f   b
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_gap(mut self, gap: u16) -> BarChart<'a> {
         self.bar_gap = gap;
         self
@@ -213,6 +218,7 @@ impl<'a> BarChart<'a> {
     /// The [`bar::Set`](crate::symbols::bar::Set) to use for displaying the bars.
     ///
     /// If not set, the default is [`bar::NINE_LEVELS`](crate::symbols::bar::NINE_LEVELS).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> BarChart<'a> {
         self.bar_set = bar_set;
         self
@@ -226,6 +232,7 @@ impl<'a> BarChart<'a> {
     /// # See also
     ///
     /// [Bar::value_style] to set the value style individually.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn value_style(mut self, style: Style) -> BarChart<'a> {
         self.value_style = style;
         self
@@ -239,12 +246,14 @@ impl<'a> BarChart<'a> {
     /// # See also
     ///
     /// [Bar::label] to set the label style individually.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn label_style(mut self, style: Style) -> BarChart<'a> {
         self.label_style = style;
         self
     }
 
     /// Set the gap between [`BarGroup`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn group_gap(mut self, gap: u16) -> BarChart<'a> {
         self.group_gap = gap;
         self
@@ -253,6 +262,7 @@ impl<'a> BarChart<'a> {
     /// Set the style of the entire chart.
     ///
     /// The style will be applied to everything that isn't styled (borders, bars, labels, ...).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> BarChart<'a> {
         self.style = style;
         self
@@ -277,6 +287,7 @@ impl<'a> BarChart<'a> {
     ///
     /// █bar██
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn direction(mut self, direction: Direction) -> BarChart<'a> {
         self.direction = direction;
         self

src/widgets/barchart/bar.rs

@@ -49,6 +49,7 @@ impl<'a> Bar<'a> {
     ///
     /// [`Bar::value_style`] to style the value.  
     /// [`Bar::text_value`] to set the displayed value.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn value(mut self, value: u64) -> Bar<'a> {
         self.value = value;
         self
@@ -61,6 +62,7 @@ impl<'a> Bar<'a> {
     /// For [`Horizontal`](crate::layout::Direction::Horizontal) bars,
     /// display the label **in** the bar.  
     /// See [`BarChart::direction`](crate::widgets::BarChart::direction) to set the direction.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn label(mut self, label: Line<'a>) -> Bar<'a> {
         self.label = Some(label);
         self
@@ -70,6 +72,7 @@ impl<'a> Bar<'a> {
     ///
     /// This will apply to every non-styled element.
     /// It can be seen and used as a default value.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Bar<'a> {
         self.style = style;
         self
@@ -80,6 +83,7 @@ impl<'a> Bar<'a> {
     /// # See also
     ///
     /// [`Bar::value`] to set the value.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn value_style(mut self, style: Style) -> Bar<'a> {
         self.value_style = style;
         self
@@ -93,6 +97,7 @@ impl<'a> Bar<'a> {
     /// # See also
     ///
     /// [`Bar::value`] to set the value.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn text_value(mut self, text_value: String) -> Bar<'a> {
         self.text_value = Some(text_value);
         self

src/widgets/barchart/bar_group.rs

@@ -26,12 +26,14 @@ pub struct BarGroup<'a> {
 
 impl<'a> BarGroup<'a> {
     /// Set the group label
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn label(mut self, label: Line<'a>) -> BarGroup<'a> {
         self.label = Some(label);
         self
     }
 
     /// Set the bars of the group to be shown
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bars(mut self, bars: &[Bar<'a>]) -> BarGroup<'a> {
         self.bars = bars.to_vec();
         self

src/widgets/block.rs

@@ -329,6 +329,7 @@ impl<'a> Block<'a> {
     /// Applies the style to all titles.
     ///
     /// If a [`Title`] already has a style, the title's style will add on top of this one.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn title_style(mut self, style: Style) -> Block<'a> {
         self.titles_style = style;
         self
@@ -352,6 +353,7 @@ impl<'a> Block<'a> {
     ///     .title("bar")
     ///     .title_alignment(Alignment::Center);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn title_alignment(mut self, alignment: Alignment) -> Block<'a> {
         self.titles_alignment = alignment;
         self
@@ -381,6 +383,7 @@ impl<'a> Block<'a> {
     ///     .title("bar")
     ///     .title_position(Position::Bottom);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn title_position(mut self, position: Position) -> Block<'a> {
         self.titles_position = position;
         self
@@ -399,6 +402,7 @@ impl<'a> Block<'a> {
     ///     .borders(Borders::ALL)
     ///     .border_style(Style::new().blue());
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn border_style(mut self, style: Style) -> Block<'a> {
         self.border_style = style;
         self
@@ -411,6 +415,7 @@ impl<'a> Block<'a> {
     /// [`Block::border_style`].
     ///
     /// This will also apply to the widget inside that block, unless the inner widget is styled.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn style(mut self, style: Style) -> Block<'a> {
         self.style = style;
         self
@@ -433,6 +438,7 @@ impl<'a> Block<'a> {
     /// # use ratatui::{prelude::*, widgets::*};
     /// Block::default().borders(Borders::LEFT | Borders::RIGHT);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn borders(mut self, flag: Borders) -> Block<'a> {
         self.borders = flag;
         self
@@ -455,6 +461,7 @@ impl<'a> Block<'a> {
     /// // │     │
     /// // ╰─────╯
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn border_type(mut self, border_type: BorderType) -> Block<'a> {
         self.border_set = border_type.to_border_set();
         self
@@ -473,6 +480,7 @@ impl<'a> Block<'a> {
     /// // ╔Block╗
     /// // ║     ║
     /// // ╚═════╝
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn border_set(mut self, border_set: border::Set) -> Block<'a> {
         self.border_set = border_set;
         self
@@ -569,6 +577,7 @@ impl<'a> Block<'a> {
     /// // │  content  │
     /// // └───────────┘
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn padding(mut self, padding: Padding) -> Block<'a> {
         self.padding = padding;
         self

src/widgets/chart.rs

@@ -43,6 +43,7 @@ impl<'a> Axis<'a> {
         since = "0.10.0",
         note = "You should use styling capabilities of `text::Line` given as argument of the `title` method to apply styling to the title."
     )]
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn title_style(mut self, style: Style) -> Axis<'a> {
         if let Some(t) = self.title {
             let title = String::from(t);
@@ -51,16 +52,19 @@ impl<'a> Axis<'a> {
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bounds(mut self, bounds: [f64; 2]) -> Axis<'a> {
         self.bounds = bounds;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn labels(mut self, labels: Vec<Span<'a>>) -> Axis<'a> {
         self.labels = Some(labels);
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Axis<'a> {
         self.style = style;
         self
@@ -70,6 +74,7 @@ impl<'a> Axis<'a> {
     /// The alignment behaves differently based on the axis:
     /// - Y-Axis: The labels are aligned within the area on the left of the axis
     /// - X-Axis: The first X-axis label is aligned relative to the Y-axis
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn labels_alignment(mut self, alignment: Alignment) -> Axis<'a> {
         self.labels_alignment = alignment;
         self
@@ -110,21 +115,25 @@ impl<'a> Dataset<'a> {
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn data(mut self, data: &'a [(f64, f64)]) -> Dataset<'a> {
         self.data = data;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn marker(mut self, marker: symbols::Marker) -> Dataset<'a> {
         self.marker = marker;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn graph_type(mut self, graph_type: GraphType) -> Dataset<'a> {
         self.graph_type = graph_type;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Dataset<'a> {
         self.style = style;
         self
@@ -215,21 +224,25 @@ impl<'a> Chart<'a> {
         }
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Chart<'a> {
         self.block = Some(block);
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Chart<'a> {
         self.style = style;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn x_axis(mut self, axis: Axis<'a>) -> Chart<'a> {
         self.x_axis = axis;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn y_axis(mut self, axis: Axis<'a>) -> Chart<'a> {
         self.y_axis = axis;
         self
@@ -250,6 +263,7 @@ impl<'a> Chart<'a> {
     /// let _chart: Chart = Chart::new(vec![])
     ///     .hidden_legend_constraints(constraints);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn hidden_legend_constraints(mut self, constraints: (Constraint, Constraint)) -> Chart<'a> {
         self.hidden_legend_constraints = constraints;
         self

src/widgets/gauge.rs

@@ -66,6 +66,7 @@ impl<'a> Gauge<'a> {
     ///
     /// The gauge is rendered in the inner portion of the block once space for borders and padding
     /// is reserved. Styles set on the block do **not** affect the bar itself.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Gauge<'a> {
         self.block = Some(block);
         self
@@ -80,6 +81,7 @@ impl<'a> Gauge<'a> {
     /// # See also
     ///
     /// See [`Gauge::ratio`] to set from a float.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn percent(mut self, percent: u16) -> Gauge<'a> {
         assert!(
             percent <= 100,
@@ -101,6 +103,7 @@ impl<'a> Gauge<'a> {
     /// # See also
     ///
     /// See [`Gauge::percent`] to set from a percentage.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn ratio(mut self, ratio: f64) -> Gauge<'a> {
         assert!(
             (0.0..=1.0).contains(&ratio),
@@ -114,6 +117,7 @@ impl<'a> Gauge<'a> {
     ///
     /// For a left-aligned label, see [`LineGauge`].
     /// If the label is not defined, it is the percentage filled.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn label<T>(mut self, label: T) -> Gauge<'a>
     where
         T: Into<Span<'a>>,
@@ -126,12 +130,14 @@ impl<'a> Gauge<'a> {
     ///
     /// This will style the block (if any non-styled) and background of the widget (everything
     /// except the bar itself). [`Block`] style set with [`Gauge::block`] takes precedence.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Gauge<'a> {
         self.style = style;
         self
     }
 
     /// Sets the style of the bar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn gauge_style(mut self, style: Style) -> Gauge<'a> {
         self.gauge_style = style;
         self
@@ -142,6 +148,7 @@ impl<'a> Gauge<'a> {
     /// This enables the use of
     /// [unicode block characters](https://en.wikipedia.org/wiki/Block_Elements).
     /// This is useful to display a higher precision bar (8 extra fractional parts per cell).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn use_unicode(mut self, unicode: bool) -> Gauge<'a> {
         self.use_unicode = unicode;
         self
@@ -265,6 +272,7 @@ pub struct LineGauge<'a> {
 
 impl<'a> LineGauge<'a> {
     /// Surrounds the `LineGauge` with a [`Block`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Self {
         self.block = Some(block);
         self
@@ -278,6 +286,7 @@ impl<'a> LineGauge<'a> {
     /// # Panics
     ///
     /// This method panics if `ratio` is **not** between 0 and 1 inclusively.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn ratio(mut self, ratio: f64) -> Self {
         assert!(
             (0.0..=1.0).contains(&ratio),
@@ -294,6 +303,7 @@ impl<'a> LineGauge<'a> {
     /// See [`symbols::line::Set`] for more information. Predefined sets are also available, see
     /// [`NORMAL`](symbols::line::NORMAL), [`DOUBLE`](symbols::line::DOUBLE) and
     /// [`THICK`](symbols::line::THICK).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn line_set(mut self, set: symbols::line::Set) -> Self {
         self.line_set = set;
         self
@@ -315,12 +325,14 @@ impl<'a> LineGauge<'a> {
     ///
     /// This will style everything except the bar itself, so basically the block (if any) and
     /// background.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Self {
         self.style = style;
         self
     }
 
     /// Sets the style of the bar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn gauge_style(mut self, style: Style) -> Self {
         self.gauge_style = style;
         self
@@ -419,19 +431,19 @@ mod tests {
     #[test]
     #[should_panic]
     fn gauge_invalid_percentage() {
-        Gauge::default().percent(110);
+        let _ = Gauge::default().percent(110);
     }
 
     #[test]
     #[should_panic]
     fn gauge_invalid_ratio_upper_bound() {
-        Gauge::default().ratio(1.1);
+        let _ = Gauge::default().ratio(1.1);
     }
 
     #[test]
     #[should_panic]
     fn gauge_invalid_ratio_lower_bound() {
-        Gauge::default().ratio(-0.5);
+        let _ = Gauge::default().ratio(-0.5);
     }
 
     #[test]

src/widgets/list.rs

@@ -23,11 +23,13 @@ impl ListState {
         &mut self.offset
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn with_selected(mut self, selected: Option<usize>) -> Self {
         self.selected = selected;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn with_offset(mut self, offset: usize) -> Self {
         self.offset = offset;
         self
@@ -62,6 +64,7 @@ impl<'a> ListItem<'a> {
         }
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> ListItem<'a> {
         self.style = style;
         self
@@ -124,26 +127,31 @@ impl<'a> List<'a> {
         }
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> List<'a> {
         self.block = Some(block);
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> List<'a> {
         self.style = style;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn highlight_symbol(mut self, highlight_symbol: &'a str) -> List<'a> {
         self.highlight_symbol = Some(highlight_symbol);
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn highlight_style(mut self, style: Style) -> List<'a> {
         self.highlight_style = style;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn repeat_highlight_symbol(mut self, repeat: bool) -> List<'a> {
         self.repeat_highlight_symbol = repeat;
         self
@@ -152,11 +160,13 @@ impl<'a> List<'a> {
     /// Set when to show the highlight spacing
     ///
     /// See [`HighlightSpacing`] about which variant affects spacing in which way
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn highlight_spacing(mut self, value: HighlightSpacing) -> Self {
         self.highlight_spacing = value;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn start_corner(mut self, corner: Corner) -> List<'a> {
         self.start_corner = corner;
         self

src/widgets/paragraph.rs

@@ -138,6 +138,7 @@ impl<'a> Paragraph<'a> {
     ///         .title("Paragraph")
     ///         .borders(Borders::ALL));
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Paragraph<'a> {
         self.block = Some(block);
         self
@@ -155,6 +156,7 @@ impl<'a> Paragraph<'a> {
     /// let paragraph = Paragraph::new("Hello, world!")
     ///    .style(Style::new().red().on_white());
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Paragraph<'a> {
         self.style = style;
         self
@@ -171,6 +173,7 @@ impl<'a> Paragraph<'a> {
     /// let paragraph = Paragraph::new("Hello, world!")
     ///   .wrap(Wrap { trim: true });
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn wrap(mut self, wrap: Wrap) -> Paragraph<'a> {
         self.wrap = Some(wrap);
         self
@@ -187,6 +190,7 @@ impl<'a> Paragraph<'a> {
     ///
     /// For more information about future scrolling design and concerns, see [RFC: Design of
     /// Scrollable Widgets](https://github.com/ratatui-org/ratatui/issues/174) on GitHub.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn scroll(mut self, offset: (Vertical, Horizontal)) -> Paragraph<'a> {
         self.scroll = offset;
         self
@@ -204,6 +208,7 @@ impl<'a> Paragraph<'a> {
     /// let paragraph = Paragraph::new("Hello World")
     ///     .alignment(Alignment::Center);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn alignment(mut self, alignment: Alignment) -> Paragraph<'a> {
         self.alignment = alignment;
         self

src/widgets/scrollbar.rs

@@ -62,18 +62,21 @@ impl ScrollbarState {
         }
     }
     /// Sets the scroll position of the scrollbar and returns the modified ScrollbarState.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn position(mut self, position: usize) -> Self {
         self.position = position;
         self
     }
 
     /// Sets the length of the scrollable content and returns the modified ScrollbarState.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn content_length(mut self, content_length: usize) -> Self {
         self.content_length = content_length;
         self
     }
 
     /// Sets the length of the viewport content and returns the modified ScrollbarState.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn viewport_content_length(mut self, viewport_content_length: usize) -> Self {
         self.viewport_content_length = viewport_content_length;
         self
@@ -204,6 +207,7 @@ impl<'a> Scrollbar<'a> {
 
     /// Sets the orientation of the scrollbar.
     /// Resets the symbols to [`DOUBLE_VERTICAL`] or [`DOUBLE_HORIZONTAL`] based on orientation
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn orientation(mut self, orientation: ScrollbarOrientation) -> Self {
         self.orientation = orientation;
         let set = if self.is_vertical() {
@@ -215,54 +219,63 @@ impl<'a> Scrollbar<'a> {
     }
 
     /// Sets the orientation and symbols for the scrollbar from a [`Set`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn orientation_and_symbol(mut self, orientation: ScrollbarOrientation, set: Set) -> Self {
         self.orientation = orientation;
         self.symbols(set)
     }
 
     /// Sets the symbol that represents the thumb of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn thumb_symbol(mut self, thumb_symbol: &'a str) -> Self {
         self.thumb_symbol = thumb_symbol;
         self
     }
 
     /// Sets the style that represents the thumb of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn thumb_style(mut self, thumb_style: Style) -> Self {
         self.thumb_style = thumb_style;
         self
     }
 
     /// Sets the symbol that represents the track of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn track_symbol(mut self, track_symbol: Option<&'a str>) -> Self {
         self.track_symbol = track_symbol;
         self
     }
 
     /// Sets the style that is used for the track of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn track_style(mut self, track_style: Style) -> Self {
         self.track_style = track_style;
         self
     }
 
     /// Sets the symbol that represents the beginning of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn begin_symbol(mut self, begin_symbol: Option<&'a str>) -> Self {
         self.begin_symbol = begin_symbol;
         self
     }
 
     /// Sets the style that is used for the beginning of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn begin_style(mut self, begin_style: Style) -> Self {
         self.begin_style = begin_style;
         self
     }
 
     /// Sets the symbol that represents the end of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn end_symbol(mut self, end_symbol: Option<&'a str>) -> Self {
         self.end_symbol = end_symbol;
         self
     }
 
     /// Sets the style that is used for the end of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn end_style(mut self, end_style: Style) -> Self {
         self.end_style = end_style;
         self
@@ -281,6 +294,7 @@ impl<'a> Scrollbar<'a> {
     ///
     /// Only sets begin_symbol, end_symbol and track_symbol if they already contain a value.
     /// If they were set to `None` explicitly, this function will respect that choice.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn symbols(mut self, symbol: Set) -> Self {
         self.thumb_symbol = symbol.thumb;
         if self.track_symbol.is_some() {
@@ -304,6 +318,7 @@ impl<'a> Scrollbar<'a> {
     /// │  └──────── thumb
     /// └─────────── begin
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Self {
         self.track_style = style;
         self.thumb_style = style;

src/widgets/sparkline.rs

@@ -18,7 +18,7 @@ use crate::{
 /// `Sparkline` can be styled either using [`Sparkline::style`] or preferably using the methods
 /// provided by the [`Stylize`](crate::style::Stylize) trait.
 ///
-/// # Builder methods
+/// # Setter methods
 ///
 /// - [`Sparkline::block`] wraps the sparkline in a [`Block`]
 /// - [`Sparkline::data`] defines the dataset, you'll almost always want to use it
@@ -81,6 +81,7 @@ impl<'a> Default for Sparkline<'a> {
 
 impl<'a> Sparkline<'a> {
     /// Wraps the sparkline with the given `block`.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Sparkline<'a> {
         self.block = Some(block);
         self
@@ -89,6 +90,7 @@ impl<'a> Sparkline<'a> {
     /// Sets the style of the entire widget.
     ///
     /// The foreground corresponds to the bars while the background is everything else.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Sparkline<'a> {
         self.style = style;
         self
@@ -106,6 +108,7 @@ impl<'a> Sparkline<'a> {
     /// frame.render_widget(sparkline, area);
     /// # }
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn data(mut self, data: &'a [u64]) -> Sparkline<'a> {
         self.data = data;
         self
@@ -115,6 +118,7 @@ impl<'a> Sparkline<'a> {
     ///
     /// Every bar will be scaled accordingly. If no max is given, this will be the max in the
     /// dataset.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn max(mut self, max: u64) -> Sparkline<'a> {
         self.max = Some(max);
         self
@@ -124,6 +128,7 @@ impl<'a> Sparkline<'a> {
     ///
     /// Can be [`symbols::bar::THREE_LEVELS`], [`symbols::bar::NINE_LEVELS`] (default) or a custom
     /// [`Set`](symbols::bar::Set).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> Sparkline<'a> {
         self.bar_set = bar_set;
         self
@@ -132,6 +137,7 @@ impl<'a> Sparkline<'a> {
     /// Sets the direction of the sparkline.
     ///
     /// [`RenderDirection::LeftToRight`] by default.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn direction(mut self, direction: RenderDirection) -> Sparkline<'a> {
         self.direction = direction;
         self

src/widgets/tabs.rs

@@ -100,6 +100,7 @@ impl<'a> Tabs<'a> {
     }
 
     /// Surrounds the `Tabs` with a [`Block`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Tabs<'a> {
         self.block = Some(block);
         self
@@ -109,6 +110,7 @@ impl<'a> Tabs<'a> {
     ///
     /// The first tab has index 0 (this is also the default index).
     /// The selected tab can have a different style with [`Tabs::highlight_style`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn select(mut self, selected: usize) -> Tabs<'a> {
         self.selected = selected;
         self
@@ -119,6 +121,7 @@ impl<'a> Tabs<'a> {
     /// This will set the given style on the entire render area.
     /// More precise style can be applied to the titles by styling the ones given to [`Tabs::new`].
     /// The selected tab can be styled differently using [`Tabs::highlight_style`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Tabs<'a> {
         self.style = style;
         self
@@ -127,6 +130,7 @@ impl<'a> Tabs<'a> {
     /// Sets the style for the highlighted tab.
     ///
     /// Highlighted tab can be selected with [`Tabs::select`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn highlight_style(mut self, style: Style) -> Tabs<'a> {
         self.highlight_style = style;
         self