chore: Correct "builder methods" in docs and add must_use on widget…

…s 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
-//! meant to be stored but used as *commands* to draw common figures in the UI.
+//! Widgets are created for each frame as they are consumed after rendered.
+//! 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