From 910ad00059c3603ba6b1751c95783f974fde88a1 Mon Sep 17 00:00:00 2001 From: Valentin271 <36198422+Valentin271@users.noreply.github.com> Date: Sat, 16 Dec 2023 13:01:07 +0100 Subject: [PATCH] chore(rustfmt): enable format_code_in_doc_comments (#695) This enables more consistently formatted code in doc comments, especially since ratatui heavily uses fluent setters. See https://rust-lang.github.io/rustfmt/?version=v1.6.0#format_code_in_doc_comments --- rustfmt.toml | 1 + src/backend.rs | 1 + src/backend/crossterm.rs | 3 +- src/backend/termion.rs | 3 +- src/buffer.rs | 16 ++++++++-- src/layout.rs | 41 +++++++++++-------------- src/lib.rs | 11 ++++--- src/style.rs | 66 ++++++++++++++++++++++++++++------------ src/style/color.rs | 2 ++ src/style/stylize.rs | 6 +++- src/terminal.rs | 17 +++++------ src/text.rs | 5 ++- src/text/line.rs | 22 +++++++++----- src/text/span.rs | 9 ++++-- src/text/text.rs | 16 +++++++--- src/title.rs | 15 +++++---- src/widgets.rs | 14 +++++---- src/widgets/block.rs | 25 ++++++++++++--- src/widgets/canvas.rs | 33 +++++++++++++++----- src/widgets/chart.rs | 47 +++++++++++++++++----------- src/widgets/list.rs | 4 +-- src/widgets/paragraph.rs | 31 ++++++++----------- src/widgets/scrollbar.rs | 12 ++++++-- src/widgets/table.rs | 58 +++++++++++++++++++++-------------- 24 files changed, 285 insertions(+), 173 deletions(-) diff --git a/rustfmt.toml b/rustfmt.toml index 38b953ad..3cb93616 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -3,3 +3,4 @@ group_imports = "StdExternalCrate" imports_granularity = "Crate" wrap_comments = true comment_width = 100 +format_code_in_doc_comments = true diff --git a/src/backend.rs b/src/backend.rs index 8907d3d1..4f570fef 100644 --- a/src/backend.rs +++ b/src/backend.rs @@ -26,6 +26,7 @@ //! //! ```rust,no_run //! use std::io::stdout; +//! //! use ratatui::prelude::*; //! //! let backend = CrosstermBackend::new(stdout()); diff --git a/src/backend/crossterm.rs b/src/backend/crossterm.rs index 3d523287..b35c3af9 100644 --- a/src/backend/crossterm.rs +++ b/src/backend/crossterm.rs @@ -43,7 +43,8 @@ use crate::{ /// # Example /// /// ```rust,no_run -/// use std::io::{stdout, stderr}; +/// use std::io::{stderr, stdout}; +/// /// use crossterm::{ /// terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}, /// ExecutableCommand, diff --git a/src/backend/termion.rs b/src/backend/termion.rs index 3fa5d4b6..8be74c0e 100644 --- a/src/backend/termion.rs +++ b/src/backend/termion.rs @@ -36,7 +36,8 @@ use crate::{ /// # Example /// /// ```rust,no_run -/// use std::io::{stdout, stderr}; +/// use std::io::{stderr, stdout}; +/// /// use ratatui::prelude::*; /// use termion::{raw::IntoRawMode, screen::IntoAlternateScreen}; /// diff --git a/src/buffer.rs b/src/buffer.rs index aede8a99..d66c76bc 100644 --- a/src/buffer.rs +++ b/src/buffer.rs @@ -140,13 +140,23 @@ impl Default for Cell { /// # Examples: /// /// ``` -/// use ratatui::{prelude::*, buffer::Cell}; +/// use ratatui::{buffer::Cell, prelude::*}; /// -/// let mut buf = Buffer::empty(Rect{x: 0, y: 0, width: 10, height: 5}); +/// let mut buf = Buffer::empty(Rect { +/// x: 0, +/// y: 0, +/// width: 10, +/// height: 5, +/// }); /// buf.get_mut(0, 2).set_symbol("x"); /// assert_eq!(buf.get(0, 2).symbol(), "x"); /// -/// buf.set_string(3, 0, "string", Style::default().fg(Color::Red).bg(Color::White)); +/// buf.set_string( +/// 3, +/// 0, +/// "string", +/// Style::default().fg(Color::Red).bg(Color::White), +/// ); /// let cell = buf.get_mut(5, 0); /// assert_eq!(cell.symbol(), "r"); /// assert_eq!(cell.fg, Color::Red); diff --git a/src/layout.rs b/src/layout.rs index 010daa64..51a8605e 100644 --- a/src/layout.rs +++ b/src/layout.rs @@ -268,7 +268,7 @@ impl Layout { /// /// let layout = Layout::new( /// Direction::Vertical, - /// [1,2,3].iter().map(|&c| Constraint::Length(c)), + /// [1, 2, 3].iter().map(|&c| Constraint::Length(c)), /// ); /// ``` pub fn new(direction: Direction, constraints: I) -> Layout @@ -353,19 +353,22 @@ impl Layout { /// Constraint::Max(2), /// ]) /// .split(Rect::new(0, 0, 10, 10)); - /// assert_eq!(layout[..], [ - /// Rect::new(0, 0, 10, 2), - /// Rect::new(0, 2, 10, 2), - /// Rect::new(0, 4, 10, 2), - /// Rect::new(0, 6, 10, 2), - /// Rect::new(0, 8, 10, 2), - /// ]); + /// assert_eq!( + /// layout[..], + /// [ + /// Rect::new(0, 0, 10, 2), + /// Rect::new(0, 2, 10, 2), + /// Rect::new(0, 4, 10, 2), + /// Rect::new(0, 6, 10, 2), + /// Rect::new(0, 8, 10, 2), + /// ] + /// ); /// /// let layout = Layout::default().constraints([Constraint::Min(0)]); /// let layout = Layout::default().constraints(&[Constraint::Min(0)]); /// let layout = Layout::default().constraints(vec![Constraint::Min(0)]); /// 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))); + /// 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(mut self, constraints: I) -> Layout @@ -660,9 +663,7 @@ impl Constraint { /// # use ratatui::prelude::*; /// # let area = Rect::default(); /// let constraints = Constraint::from_lengths([1, 2, 3]); - /// let layout = Layout::default() - /// .constraints(constraints) - /// .split(area); + /// let layout = Layout::default().constraints(constraints).split(area); /// ``` pub fn from_lengths(lengths: T) -> Vec where @@ -679,9 +680,7 @@ impl Constraint { /// # use ratatui::prelude::*; /// # let area = Rect::default(); /// let constraints = Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]); - /// let layout = Layout::default() - /// .constraints(constraints) - /// .split(area); + /// let layout = Layout::default().constraints(constraints).split(area); /// ``` pub fn from_ratios(ratios: T) -> Vec where @@ -701,9 +700,7 @@ impl Constraint { /// # use ratatui::prelude::*; /// # let area = Rect::default(); /// let constraints = Constraint::from_percentages([25, 50, 25]); - /// let layout = Layout::default() - /// .constraints(constraints) - /// .split(area); + /// let layout = Layout::default().constraints(constraints).split(area); /// ``` pub fn from_percentages(percentages: T) -> Vec where @@ -723,9 +720,7 @@ impl Constraint { /// # use ratatui::prelude::*; /// # let area = Rect::default(); /// let constraints = Constraint::from_maxes([1, 2, 3]); - /// let layout = Layout::default() - /// .constraints(constraints) - /// .split(area); + /// let layout = Layout::default().constraints(constraints).split(area); /// ``` pub fn from_maxes(maxes: T) -> Vec where @@ -742,9 +737,7 @@ impl Constraint { /// # use ratatui::prelude::*; /// # let area = Rect::default(); /// let constraints = Constraint::from_mins([1, 2, 3]); - /// let layout = Layout::default() - /// .constraints(constraints) - /// .split(area); + /// let layout = Layout::default().constraints(constraints).split(area); /// ``` pub fn from_mins(mins: T) -> Vec where diff --git a/src/lib.rs b/src/lib.rs index da89bfa2..678b4fc4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -110,10 +110,11 @@ //! //! ```rust,no_run //! use std::io::{self, stdout}; +//! //! use crossterm::{ //! event::{self, Event, KeyCode}, +//! terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}, //! ExecutableCommand, -//! terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen} //! }; //! use ratatui::{prelude::*, widgets::*}; //! @@ -139,7 +140,7 @@ //! if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') { //! return Ok(true); //! } -//! } +//! } //! } //! Ok(false) //! } @@ -174,7 +175,7 @@ //! Constraint::Length(1), //! Constraint::Min(0), //! Constraint::Length(1), -//! ] +//! ], //! ) //! .split(frame.size()); //! frame.render_widget( @@ -188,7 +189,7 @@ //! //! let inner_layout = Layout::new( //! Direction::Horizontal, -//! [Constraint::Percentage(50), Constraint::Percentage(50)] +//! [Constraint::Percentage(50), Constraint::Percentage(50)], //! ) //! .split(main_layout[1]); //! frame.render_widget( @@ -230,7 +231,7 @@ //! Constraint::Length(1), //! Constraint::Length(1), //! Constraint::Min(0), -//! ] +//! ], //! ) //! .split(frame.size()); //! diff --git a/src/style.rs b/src/style.rs index 1beebfea..3c2c7f99 100644 --- a/src/style.rs +++ b/src/style.rs @@ -16,9 +16,9 @@ //! use ratatui::prelude::*; //! //! let heading_style = Style::new() -//! .fg(Color::Black) -//! .bg(Color::Green) -//! .add_modifier(Modifier::ITALIC | Modifier::BOLD); +//! .fg(Color::Black) +//! .bg(Color::Green) +//! .add_modifier(Modifier::ITALIC | Modifier::BOLD); //! let span = Span::styled("hello", heading_style); //! ``` //! @@ -44,16 +44,24 @@ //! use ratatui::{prelude::*, widgets::*}; //! //! assert_eq!( -//! "hello".red().on_blue().bold(), +//! "hello".red().on_blue().bold(), //! Span::styled( //! "hello", -//! Style::default().fg(Color::Red).bg(Color::Blue).add_modifier(Modifier::BOLD)) +//! Style::default() +//! .fg(Color::Red) +//! .bg(Color::Blue) +//! .add_modifier(Modifier::BOLD) +//! ) //! ); //! //! assert_eq!( //! Paragraph::new("hello").red().on_blue().bold(), -//! Paragraph::new("hello") -//! .style(Style::default().fg(Color::Red).bg(Color::Blue).add_modifier(Modifier::BOLD)) +//! Paragraph::new("hello").style( +//! Style::default() +//! .fg(Color::Red) +//! .bg(Color::Blue) +//! .add_modifier(Modifier::BOLD) +//! ) //! ); //! ``` //! @@ -113,7 +121,7 @@ impl fmt::Debug for Modifier { /// Style lets you control the main characteristics of the displayed elements. /// /// ```rust -/// use ratatui::{prelude::*}; +/// use ratatui::prelude::*; /// /// Style::default() /// .fg(Color::Black) @@ -135,18 +143,24 @@ impl fmt::Debug for Modifier { /// just S3. /// /// ```rust -/// use ratatui::{prelude::*}; +/// use ratatui::prelude::*; /// /// let styles = [ -/// Style::default().fg(Color::Blue).add_modifier(Modifier::BOLD | Modifier::ITALIC), -/// Style::default().bg(Color::Red).add_modifier(Modifier::UNDERLINED), +/// Style::default() +/// .fg(Color::Blue) +/// .add_modifier(Modifier::BOLD | Modifier::ITALIC), +/// Style::default() +/// .bg(Color::Red) +/// .add_modifier(Modifier::UNDERLINED), /// #[cfg(feature = "underline-color")] /// Style::default().underline_color(Color::Green), -/// Style::default().fg(Color::Yellow).remove_modifier(Modifier::ITALIC), +/// Style::default() +/// .fg(Color::Yellow) +/// .remove_modifier(Modifier::ITALIC), /// ]; /// let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 1)); /// for style in &styles { -/// buffer.get_mut(0, 0).set_style(*style); +/// buffer.get_mut(0, 0).set_style(*style); /// } /// assert_eq!( /// Style { @@ -165,15 +179,17 @@ impl fmt::Debug for Modifier { /// reset all properties until that point use [`Style::reset`]. /// /// ``` -/// use ratatui::{prelude::*}; +/// use ratatui::prelude::*; /// /// let styles = [ -/// Style::default().fg(Color::Blue).add_modifier(Modifier::BOLD | Modifier::ITALIC), +/// Style::default() +/// .fg(Color::Blue) +/// .add_modifier(Modifier::BOLD | Modifier::ITALIC), /// Style::reset().fg(Color::Yellow), /// ]; /// let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 1)); /// for style in &styles { -/// buffer.get_mut(0, 0).set_style(*style); +/// buffer.get_mut(0, 0).set_style(*style); /// } /// assert_eq!( /// Style { @@ -285,9 +301,18 @@ impl Style { /// /// ```rust /// # use ratatui::prelude::*; - /// let style = Style::default().underline_color(Color::Blue).add_modifier(Modifier::UNDERLINED); - /// let diff = Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED); - /// assert_eq!(style.patch(diff), Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED)); + /// let style = Style::default() + /// .underline_color(Color::Blue) + /// .add_modifier(Modifier::UNDERLINED); + /// let diff = Style::default() + /// .underline_color(Color::Red) + /// .add_modifier(Modifier::UNDERLINED); + /// assert_eq!( + /// style.patch(diff), + /// Style::default() + /// .underline_color(Color::Red) + /// .add_modifier(Modifier::UNDERLINED) + /// ); /// ``` #[cfg(feature = "underline-color")] #[must_use = "`underline_color` returns the modified style without modifying the original"] @@ -349,7 +374,8 @@ impl Style { /// let combined = style_1.patch(style_2); /// assert_eq!( /// Style::default().patch(style_1).patch(style_2), - /// Style::default().patch(combined)); + /// Style::default().patch(combined) + /// ); /// ``` #[must_use = "`patch` returns the modified style without modifying the original"] pub fn patch(mut self, other: Style) -> Style { diff --git a/src/style/color.rs b/src/style/color.rs index 59a0bab9..ac7fc435 100644 --- a/src/style/color.rs +++ b/src/style/color.rs @@ -39,6 +39,7 @@ use std::{ /// /// ``` /// use std::str::FromStr; +/// /// use ratatui::prelude::*; /// /// assert_eq!(Color::from_str("red"), Ok(Color::Red)); @@ -147,6 +148,7 @@ impl std::error::Error for ParseColorError {} /// /// ``` /// use std::str::FromStr; +/// /// use ratatui::prelude::*; /// /// let color: Color = Color::from_str("blue").unwrap(); diff --git a/src/style/stylize.rs b/src/style/stylize.rs index f3f9599a..8a3cd821 100644 --- a/src/style/stylize.rs +++ b/src/style/stylize.rs @@ -127,7 +127,11 @@ macro_rules! modifier { /// "world".green().on_yellow().not_bold(), /// ]); /// let paragraph = Paragraph::new(line).italic().underlined(); -/// let block = Block::default().title("Title").borders(Borders::ALL).on_white().bold(); +/// let block = Block::default() +/// .title("Title") +/// .borders(Borders::ALL) +/// .on_white() +/// .bold(); /// ``` pub trait Stylize<'a, T>: Sized { #[must_use = "`bg` returns the modified style without modifying the original"] diff --git a/src/terminal.rs b/src/terminal.rs index 6acd16cc..5ec9049b 100644 --- a/src/terminal.rs +++ b/src/terminal.rs @@ -12,6 +12,7 @@ //! //! ```rust,no_run //! use std::io::stdout; +//! //! use ratatui::{prelude::*, widgets::Paragraph}; //! //! let backend = CrosstermBackend::new(stdout()); @@ -108,6 +109,7 @@ pub struct TerminalOptions { /// /// ```rust,no_run /// use std::io::stdout; +/// /// use ratatui::{prelude::*, widgets::Paragraph}; /// /// let backend = CrosstermBackend::new(stdout()); @@ -198,10 +200,7 @@ where /// # use ratatui::{prelude::*, backend::TestBackend}; /// let backend = CrosstermBackend::new(stdout()); /// let viewport = Viewport::Fixed(Rect::new(0, 0, 10, 10)); - /// let terminal = Terminal::with_options( - /// backend, - /// TerminalOptions { viewport }, - /// )?; + /// let terminal = Terminal::with_options(backend, TerminalOptions { viewport })?; /// # std::io::Result::Ok(()) /// ``` pub fn with_options(mut backend: B, options: TerminalOptions) -> io::Result> { @@ -459,8 +458,9 @@ where /// Paragraph::new(Line::from(vec![ /// Span::raw("This line will be added "), /// Span::styled("before", Style::default().fg(Color::Blue)), - /// Span::raw(" the current viewport") - /// ])).render(buf.area, buf); + /// Span::raw(" the current viewport"), + /// ])) + /// .render(buf.area, buf); /// }); /// ``` pub fn insert_before(&mut self, height: u16, draw_fn: F) -> io::Result<()> @@ -628,10 +628,7 @@ impl Frame<'_> { /// # let mut terminal = Terminal::new(backend).unwrap(); /// # let mut frame = terminal.get_frame(); /// let mut state = ListState::default().with_selected(Some(1)); - /// let list = List::new(vec![ - /// ListItem::new("Item 1"), - /// ListItem::new("Item 2"), - /// ]); + /// let list = List::new(vec![ListItem::new("Item 1"), ListItem::new("Item 2")]); /// let area = Rect::new(0, 0, 5, 5); /// frame.render_stateful_widget(list, area, &mut state); /// ``` diff --git a/src/text.rs b/src/text.rs index 94187715..ed778865 100644 --- a/src/text.rs +++ b/src/text.rs @@ -31,9 +31,8 @@ //! // Converted to Line(vec![ //! // Span { content: Cow::Borrowed("My title"), style: Style { fg: Some(Color::Yellow), .. } //! // ]) -//! let block = Block::default().title( -//! Span::styled("My title", Style::default().fg(Color::Yellow)) -//! ); +//! let block = +//! Block::default().title(Span::styled("My title", Style::default().fg(Color::Yellow))); //! //! // A string with multiple styles. //! // Converted to Line(vec![ diff --git a/src/text/line.rs b/src/text/line.rs index 6247c1d3..d0af2ed6 100644 --- a/src/text/line.rs +++ b/src/text/line.rs @@ -39,7 +39,9 @@ impl<'a> Line<'a> { /// /// ```rust /// # use ratatui::prelude::*; - /// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC); + /// let style = Style::default() + /// .fg(Color::Yellow) + /// .add_modifier(Modifier::ITALIC); /// Line::styled("My text", style); /// Line::styled(String::from("My text"), style); /// ``` @@ -75,12 +77,14 @@ impl<'a> Line<'a> { /// /// ```rust /// use std::iter::Iterator; + /// /// use ratatui::{prelude::*, text::StyledGrapheme}; /// /// let line = Line::styled("Text", Style::default().fg(Color::Yellow)); /// let style = Style::default().fg(Color::Green).bg(Color::Black); /// assert_eq!( - /// line.styled_graphemes(style).collect::>(), + /// line.styled_graphemes(style) + /// .collect::>(), /// vec![ /// StyledGrapheme::new("T", Style::default().fg(Color::Yellow).bg(Color::Black)), /// StyledGrapheme::new("e", Style::default().fg(Color::Yellow).bg(Color::Black)), @@ -104,11 +108,10 @@ impl<'a> Line<'a> { /// /// ```rust /// # use ratatui::prelude::*; - /// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC); - /// let mut raw_line = Line::from(vec![ - /// Span::raw("My"), - /// Span::raw(" text"), - /// ]); + /// let style = Style::default() + /// .fg(Color::Yellow) + /// .add_modifier(Modifier::ITALIC); + /// let mut raw_line = Line::from(vec![Span::raw("My"), Span::raw(" text")]); /// let mut styled_line = Line::from(vec![ /// Span::styled("My", style), /// Span::styled(" text", style), @@ -156,7 +159,10 @@ impl<'a> Line<'a> { /// # use ratatui::prelude::*; /// let mut line = Line::from("Hi, what's up?"); /// assert_eq!(None, line.alignment); - /// assert_eq!(Some(Alignment::Right), line.alignment(Alignment::Right).alignment) + /// assert_eq!( + /// Some(Alignment::Right), + /// line.alignment(Alignment::Right).alignment + /// ) /// ``` pub fn alignment(self, alignment: Alignment) -> Self { Self { diff --git a/src/text/span.rs b/src/text/span.rs index cdf8dff5..3a38c5c1 100644 --- a/src/text/span.rs +++ b/src/text/span.rs @@ -68,7 +68,10 @@ use crate::style::{Style, Styled}; /// use ratatui::prelude::*; /// /// let span = Span::raw("test content").green().on_yellow().italic(); -/// let span = Span::raw(String::from("test content")).green().on_yellow().italic(); +/// let span = Span::raw(String::from("test content")) +/// .green() +/// .on_yellow() +/// .italic(); /// ``` /// /// [`Line`]: crate::text::Line @@ -212,12 +215,14 @@ impl<'a> Span<'a> { /// /// ```rust /// use std::iter::Iterator; + /// /// use ratatui::{prelude::*, text::StyledGrapheme}; /// /// let span = Span::styled("Test", Style::new().green().italic()); /// let style = Style::new().red().on_yellow(); /// assert_eq!( - /// span.styled_graphemes(style).collect::>(), + /// span.styled_graphemes(style) + /// .collect::>(), /// vec![ /// StyledGrapheme::new("T", Style::new().green().on_yellow().italic()), /// StyledGrapheme::new("e", Style::new().green().on_yellow().italic()), diff --git a/src/text/text.rs b/src/text/text.rs index ede3f911..e72dd8b2 100644 --- a/src/text/text.rs +++ b/src/text/text.rs @@ -13,7 +13,9 @@ use crate::style::Style; /// ```rust /// use ratatui::prelude::*; /// -/// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC); +/// let style = Style::default() +/// .fg(Color::Yellow) +/// .add_modifier(Modifier::ITALIC); /// /// // An initial two lines of `Text` built from a `&str` /// let mut text = Text::from("The first line\nThe second line"); @@ -62,7 +64,9 @@ impl<'a> Text<'a> { /// /// ```rust /// # use ratatui::prelude::*; - /// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC); + /// let style = Style::default() + /// .fg(Color::Yellow) + /// .add_modifier(Modifier::ITALIC); /// Text::styled("The first line\nThe second line", style); /// Text::styled(String::from("The first line\nThe second line"), style); /// ``` @@ -107,7 +111,9 @@ impl<'a> Text<'a> { /// /// ```rust /// # use ratatui::prelude::*; - /// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC); + /// let style = Style::default() + /// .fg(Color::Yellow) + /// .add_modifier(Modifier::ITALIC); /// let mut raw_text = Text::raw("The first line\nThe second line"); /// let styled_text = Text::styled(String::from("The first line\nThe second line"), style); /// assert_ne!(raw_text, styled_text); @@ -128,7 +134,9 @@ impl<'a> Text<'a> { /// /// ```rust /// # use ratatui::prelude::*; - /// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC); + /// let style = Style::default() + /// .fg(Color::Yellow) + /// .add_modifier(Modifier::ITALIC); /// let mut text = Text::styled("The first line\nThe second line", style); /// /// text.reset_style(); diff --git a/src/title.rs b/src/title.rs index ae405265..13a9fec4 100644 --- a/src/title.rs +++ b/src/title.rs @@ -29,14 +29,15 @@ use crate::{layout::Alignment, text::Line}; /// ``` /// use ratatui::{prelude::*, widgets::block::*}; /// -/// Title::from( -/// Line::from(vec!["Q".white().underlined(), "uit".gray()]) -/// ); +/// Title::from(Line::from(vec!["Q".white().underlined(), "uit".gray()])); /// ``` /// /// Complete example /// ``` -/// use ratatui::{prelude::*, widgets::{*, block::*}}; +/// use ratatui::{ +/// prelude::*, +/// widgets::{block::*, *}, +/// }; /// /// Title::from("Title") /// .position(Position::Top) @@ -69,11 +70,9 @@ pub struct Title<'a> { /// # Example /// /// ``` -/// use ratatui::widgets::{*, block::*}; +/// use ratatui::widgets::{block::*, *}; /// -/// Block::new().title( -/// Title::from("title").position(Position::Bottom) -/// ); +/// Block::new().title(Title::from("title").position(Position::Bottom)); /// ``` #[derive(Debug, Default, Display, EnumString, Clone, Copy, PartialEq, Eq, Hash)] pub enum Position { diff --git a/src/widgets.rs b/src/widgets.rs index a85eafde..639c3ca6 100644 --- a/src/widgets.rs +++ b/src/widgets.rs @@ -130,6 +130,7 @@ pub trait Widget { /// /// ```rust,no_run /// use std::io; +/// /// use ratatui::{backend::TestBackend, prelude::*, widgets::*}; /// /// // Let's say we have some events to display. @@ -139,7 +140,7 @@ pub trait Widget { /// // `state` is the state that can be modified by the UI. It stores the index of the selected /// // item as well as the offset computed during the previous draw call (used to implement /// // natural scrolling). -/// state: ListState +/// state: ListState, /// } /// /// impl Events { @@ -199,16 +200,17 @@ pub trait Widget { /// # let backend = TestBackend::new(5, 5); /// # let mut terminal = Terminal::new(backend).unwrap(); /// -/// let mut events = Events::new(vec![ -/// String::from("Item 1"), -/// String::from("Item 2") -/// ]); +/// let mut events = Events::new(vec![String::from("Item 1"), String::from("Item 2")]); /// /// loop { /// terminal.draw(|f| { /// // The items managed by the application are transformed to something /// // that is understood by ratatui. -/// let items: Vec= events.items.iter().map(|i| ListItem::new(i.as_str())).collect(); +/// let items: Vec = events +/// .items +/// .iter() +/// .map(|i| ListItem::new(i.as_str())) +/// .collect(); /// // The `List` widget is then built with those items. /// let list = List::new(items); /// // Finally the widget is rendered using the associated state. `events.state` is diff --git a/src/widgets/block.rs b/src/widgets/block.rs index 9d7500b5..9a65c4c2 100644 --- a/src/widgets/block.rs +++ b/src/widgets/block.rs @@ -220,7 +220,10 @@ impl Padding { /// /// You may also use multiple titles like in the following: /// ``` -/// use ratatui::{prelude::*, widgets::{*, block::*}}; +/// use ratatui::{ +/// prelude::*, +/// widgets::{block::*, *}, +/// }; /// /// Block::default() /// .title("Title 1") @@ -301,7 +304,10 @@ impl<'a> Block<'a> { /// the leftover space) /// - Two titles with the same alignment (notice the left titles are separated) /// ``` - /// use ratatui::{prelude::*, widgets::{*, block::*}}; + /// use ratatui::{ + /// prelude::*, + /// widgets::{block::*, *}, + /// }; /// /// Block::default() /// .title("Title") // By default in the top left corner @@ -344,7 +350,10 @@ impl<'a> Block<'a> { /// This example aligns all titles in the center except the "right" title which explicitly sets /// [`Alignment::Right`]. /// ``` - /// use ratatui::{prelude::*, widgets::{*, block::*}}; + /// use ratatui::{ + /// prelude::*, + /// widgets::{block::*, *}, + /// }; /// /// Block::default() /// // This title won't be aligned in the center @@ -374,7 +383,10 @@ impl<'a> Block<'a> { /// This example positions all titles on the bottom except the "top" title which explicitly sets /// [`Position::Top`]. /// ``` - /// use ratatui::{prelude::*, widgets::{*, block::*}}; + /// use ratatui::{ + /// prelude::*, + /// widgets::{block::*, *}, + /// }; /// /// Block::default() /// // This title won't be aligned in the center @@ -455,7 +467,10 @@ impl<'a> Block<'a> { /// /// ``` /// # use ratatui::{prelude::*, widgets::*}; - /// Block::default().title("Block").borders(Borders::ALL).border_type(BorderType::Rounded); + /// Block::default() + /// .title("Block") + /// .borders(Borders::ALL) + /// .border_type(BorderType::Rounded); /// // Renders /// // ╭Block╮ /// // │ │ diff --git a/src/widgets/canvas.rs b/src/widgets/canvas.rs index e9ab5a5f..1ff9e8f5 100644 --- a/src/widgets/canvas.rs +++ b/src/widgets/canvas.rs @@ -457,7 +457,13 @@ impl<'a> Context<'a> { /// ``` /// use ratatui::{prelude::*, widgets::canvas::*}; /// - /// let ctx = Context::new(100, 100, [-180.0, 180.0], [-90.0, 90.0], symbols::Marker::Braille); + /// let ctx = Context::new( + /// 100, + /// 100, + /// [-180.0, 180.0], + /// [-90.0, 90.0], + /// symbols::Marker::Braille, + /// ); /// ``` pub fn new( width: u16, @@ -554,7 +560,10 @@ impl<'a> Context<'a> { /// # Examples /// /// ``` -/// use ratatui::{style::Color, widgets::{*, canvas::*}}; +/// use ratatui::{ +/// style::Color, +/// widgets::{canvas::*, *}, +/// }; /// /// Canvas::default() /// .block(Block::default().title("Canvas").borders(Borders::ALL)) @@ -563,7 +572,7 @@ impl<'a> Context<'a> { /// .paint(|ctx| { /// ctx.draw(&Map { /// resolution: MapResolution::High, -/// color: Color::White +/// color: Color::White, /// }); /// ctx.layer(); /// ctx.draw(&Line { @@ -578,7 +587,7 @@ impl<'a> Context<'a> { /// y: 20.0, /// width: 10.0, /// height: 10.0, -/// color: Color::Red +/// color: Color::Red, /// }); /// }); /// ``` @@ -666,10 +675,18 @@ where /// ``` /// use ratatui::{prelude::*, widgets::canvas::*}; /// - /// Canvas::default().marker(symbols::Marker::Braille).paint(|ctx| {}); - /// Canvas::default().marker(symbols::Marker::HalfBlock).paint(|ctx| {}); - /// Canvas::default().marker(symbols::Marker::Dot).paint(|ctx| {}); - /// Canvas::default().marker(symbols::Marker::Block).paint(|ctx| {}); + /// Canvas::default() + /// .marker(symbols::Marker::Braille) + /// .paint(|ctx| {}); + /// Canvas::default() + /// .marker(symbols::Marker::HalfBlock) + /// .paint(|ctx| {}); + /// Canvas::default() + /// .marker(symbols::Marker::Dot) + /// .paint(|ctx| {}); + /// Canvas::default() + /// .marker(symbols::Marker::Block) + /// .paint(|ctx| {}); /// ``` pub fn marker(mut self, marker: symbols::Marker) -> Canvas<'a, F> { self.marker = marker; diff --git a/src/widgets/chart.rs b/src/widgets/chart.rs index 70fbfd3b..66d1304e 100644 --- a/src/widgets/chart.rs +++ b/src/widgets/chart.rs @@ -279,16 +279,32 @@ struct ChartLayout { /// ]; /// Chart::new(datasets) /// .block(Block::default().title("Chart")) -/// .x_axis(Axis::default() -/// .title(Span::styled("X Axis", Style::default().fg(Color::Red))) -/// .style(Style::default().fg(Color::White)) -/// .bounds([0.0, 10.0]) -/// .labels(["0.0", "5.0", "10.0"].iter().cloned().map(Span::from).collect())) -/// .y_axis(Axis::default() -/// .title(Span::styled("Y Axis", Style::default().fg(Color::Red))) -/// .style(Style::default().fg(Color::White)) -/// .bounds([0.0, 10.0]) -/// .labels(["0.0", "5.0", "10.0"].iter().cloned().map(Span::from).collect())); +/// .x_axis( +/// Axis::default() +/// .title(Span::styled("X Axis", Style::default().fg(Color::Red))) +/// .style(Style::default().fg(Color::White)) +/// .bounds([0.0, 10.0]) +/// .labels( +/// ["0.0", "5.0", "10.0"] +/// .iter() +/// .cloned() +/// .map(Span::from) +/// .collect(), +/// ), +/// ) +/// .y_axis( +/// Axis::default() +/// .title(Span::styled("Y Axis", Style::default().fg(Color::Red))) +/// .style(Style::default().fg(Color::White)) +/// .bounds([0.0, 10.0]) +/// .labels( +/// ["0.0", "5.0", "10.0"] +/// .iter() +/// .cloned() +/// .map(Span::from) +/// .collect(), +/// ), +/// ); /// ``` #[derive(Debug, Default, Clone, PartialEq)] pub struct Chart<'a> { @@ -352,14 +368,10 @@ impl<'a> Chart<'a> { /// /// ``` /// # use ratatui::{prelude::*, widgets::*}; - /// let constraints = ( - /// Constraint::Ratio(1, 3), - /// Constraint::Ratio(1, 4) - /// ); + /// let constraints = (Constraint::Ratio(1, 3), Constraint::Ratio(1, 4)); /// // Hide the legend when either its width is greater than 33% of the total widget width /// // or if its height is greater than 25% of the total widget height. - /// let _chart: Chart = Chart::new(vec![]) - /// .hidden_legend_constraints(constraints); + /// 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> { @@ -376,8 +388,7 @@ impl<'a> Chart<'a> { /// /// ``` /// # use ratatui::widgets::{Chart, LegendPosition}; - /// let _chart: Chart = Chart::new(vec![]) - /// .legend_position(Some(LegendPosition::TopLeft)); + /// let _chart: Chart = Chart::new(vec![]).legend_position(Some(LegendPosition::TopLeft)); /// ``` pub fn legend_position(mut self, position: Option) -> Chart<'a> { self.legend_position = position; diff --git a/src/widgets/list.rs b/src/widgets/list.rs index 1dccdd4b..b96b8cac 100644 --- a/src/widgets/list.rs +++ b/src/widgets/list.rs @@ -42,7 +42,7 @@ use crate::{ /// let mut state = ListState::default(); /// /// *state.offset_mut() = 1; // display the second item and onwards -/// state.select(Some(3)); // select the forth item (0-indexed) +/// state.select(Some(3)); // select the forth item (0-indexed) /// /// frame.render_stateful_widget(list, area, &mut state); /// # } @@ -452,7 +452,7 @@ impl<'a> List<'a> { /// # use ratatui::{prelude::*, widgets::*}; /// let list = List::new([ /// Text::styled("Item 1", Style::default().red()), - /// Text::styled("Item 2", Style::default().red()) + /// Text::styled("Item 2", Style::default().red()), /// ]); /// ``` /// diff --git a/src/widgets/paragraph.rs b/src/widgets/paragraph.rs index 6d351341..fe5c28e3 100644 --- a/src/widgets/paragraph.rs +++ b/src/widgets/paragraph.rs @@ -29,16 +29,14 @@ fn get_line_offset(line_width: u16, text_area_width: u16, alignment: Alignment) /// let text = vec![ /// Line::from(vec![ /// Span::raw("First"), -/// Span::styled("line",Style::new().green().italic()), +/// Span::styled("line", Style::new().green().italic()), /// ".".into(), /// ]), /// Line::from("Second line".red()), /// "Third line".into(), /// ]; /// Paragraph::new(text) -/// .block(Block::new() -/// .title("Paragraph") -/// .borders(Borders::ALL)) +/// .block(Block::new().title("Paragraph").borders(Borders::ALL)) /// .style(Style::new().white().on_black()) /// .alignment(Alignment::Center) /// .wrap(Wrap { trim: true }); @@ -66,9 +64,11 @@ pub struct Paragraph<'a> { /// ``` /// use ratatui::{prelude::*, widgets::*}; /// -/// let bullet_points = Text::from(r#"Some indented points: +/// let bullet_points = Text::from( +/// r#"Some indented points: /// - First thing goes here and is long so that it wraps -/// - Here is another point that is long enough to wrap"#); +/// - Here is another point that is long enough to wrap"#, +/// ); /// /// // With leading spaces trimmed (window width of 30 chars): /// Paragraph::new(bullet_points.clone()).wrap(Wrap { trim: true }); @@ -108,10 +108,8 @@ impl<'a> Paragraph<'a> { /// let paragraph = Paragraph::new("Hello, world!"); /// let paragraph = Paragraph::new(String::from("Hello, world!")); /// let paragraph = Paragraph::new(Text::raw("Hello, world!")); - /// let paragraph = Paragraph::new( - /// Text::styled("Hello, world!", Style::default())); - /// let paragraph = Paragraph::new( - /// Line::from(vec!["Hello, ".into(), "world!".red()])); + /// let paragraph = Paragraph::new(Text::styled("Hello, world!", Style::default())); + /// let paragraph = Paragraph::new(Line::from(vec!["Hello, ".into(), "world!".red()])); /// ``` pub fn new(text: T) -> Paragraph<'a> where @@ -134,9 +132,7 @@ impl<'a> Paragraph<'a> { /// ```rust /// # use ratatui::{prelude::*, widgets::*}; /// let paragraph = Paragraph::new("Hello, world!") - /// .block(Block::default() - /// .title("Paragraph") - /// .borders(Borders::ALL)); + /// .block(Block::default().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> { @@ -153,8 +149,7 @@ impl<'a> Paragraph<'a> { /// /// ```rust /// # use ratatui::{prelude::*, widgets::*}; - /// let paragraph = Paragraph::new("Hello, world!") - /// .style(Style::new().red().on_white()); + /// 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> { @@ -170,8 +165,7 @@ impl<'a> Paragraph<'a> { /// /// ```rust /// # use ratatui::{prelude::*, widgets::*}; - /// let paragraph = Paragraph::new("Hello, world!") - /// .wrap(Wrap { trim: true }); + /// 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> { @@ -205,8 +199,7 @@ impl<'a> Paragraph<'a> { /// /// ```rust /// # use ratatui::{prelude::*, widgets::*}; - /// let paragraph = Paragraph::new("Hello World") - /// .alignment(Alignment::Center); + /// 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> { diff --git a/src/widgets/scrollbar.rs b/src/widgets/scrollbar.rs index 3d1d17a5..1fb962fc 100644 --- a/src/widgets/scrollbar.rs +++ b/src/widgets/scrollbar.rs @@ -150,7 +150,11 @@ pub enum ScrollbarOrientation { /// /// let vertical_scroll = 0; // from app state /// -/// let items = vec![Line::from("Item 1"), Line::from("Item 2"), Line::from("Item 3")]; +/// let items = vec![ +/// Line::from("Item 1"), +/// Line::from("Item 2"), +/// Line::from("Item 3"), +/// ]; /// let paragraph = Paragraph::new(items.clone()) /// .scroll((vertical_scroll as u16, 0)) /// .block(Block::new().borders(Borders::RIGHT)); // to show a background for the scrollbar @@ -163,12 +167,14 @@ pub enum ScrollbarOrientation { /// /// let area = frame.size(); /// frame.render_widget(paragraph, area); -/// frame.render_stateful_widget(scrollbar, +/// frame.render_stateful_widget( +/// scrollbar, /// area.inner(&Margin { /// vertical: 1, /// horizontal: 0, /// }), // using a inner vertical margin of 1 unit makes the scrollbar inside the block -/// &mut scrollbar_state); +/// &mut scrollbar_state, +/// ); /// # } /// ``` #[derive(Debug, Clone, Eq, PartialEq, Hash)] diff --git a/src/widgets/table.rs b/src/widgets/table.rs index 3977aabe..0d98f5c8 100644 --- a/src/widgets/table.rs +++ b/src/widgets/table.rs @@ -58,30 +58,27 @@ use crate::{ /// /// let rows = [Row::new(vec!["Cell1", "Cell2", "Cell3"])]; /// // Columns widths are constrained in the same way as Layout... -/// let widths = [Constraint::Length(5), Constraint::Length(5), Constraint::Length(10)]; +/// let widths = [ +/// Constraint::Length(5), +/// Constraint::Length(5), +/// Constraint::Length(10), +/// ]; /// let table = Table::new(rows, widths) -/// /// // ...and they can be separated by a fixed spacing. /// .column_spacing(1) -/// /// // You can set the style of the entire Table. /// .style(Style::new().blue()) -/// /// // It has an optional header, which is simply a Row always visible at the top. /// .header( /// Row::new(vec!["Col1", "Col2", "Col3"]) /// .style(Style::new().bold()) /// // To add space between the header and the rest of the rows, specify the margin -/// .bottom_margin(1) +/// .bottom_margin(1), /// ) -/// /// // As any other widget, a Table can be wrapped in a Block. /// .block(Block::default().title("Table")) -/// -/// /// // The selected row and its content can also be styled. /// .highlight_style(Style::new().reversed()) -/// /// // ...and potentially show a symbol in front of the selection. /// .highlight_symbol(">>"); /// ``` @@ -95,8 +92,7 @@ use crate::{ /// let row = Row::new(vec!["Row11", "Row12", "Row13"]); /// /// // You can style the entire row. -/// let row = Row::new(vec!["Row21", "Row22", "Row23"]) -/// .style(Style::new().red()); +/// let row = Row::new(vec!["Row21", "Row22", "Row23"]).style(Style::new().red()); /// /// // If you need more control over the styling, create Cells directly /// let row = Row::new(vec![ @@ -104,7 +100,7 @@ use crate::{ /// Cell::from("Row32").style(Style::default().fg(Color::Yellow)), /// Cell::from(Line::from(vec![ /// Span::raw("Row"), -/// Span::styled("33", Style::default().fg(Color::Green)) +/// Span::styled("33", Style::default().fg(Color::Green)), /// ])), /// ]); /// @@ -113,7 +109,8 @@ use crate::{ /// Cell::from("Row\n41"), /// Cell::from("Row\n42"), /// Cell::from("Row\n43"), -/// ]).height(2); +/// ]) +/// .height(2); /// ``` /// /// Cells can be created from anything that can be converted to [`Text`]. See [`Cell`] for more @@ -127,7 +124,7 @@ use crate::{ /// Cell::from(Span::styled("styled span", Style::new().red())); /// Cell::from(Line::from(vec![ /// Span::raw("a vec of "), -/// Span::styled("spans", Style::new().bold()) +/// Span::styled("spans", Style::new().bold()), /// ])); /// Cell::from(Text::from("text")); /// ``` @@ -139,7 +136,11 @@ use crate::{ /// use ratatui::{prelude::*, widgets::*}; /// /// let rows = [Row::new(vec!["Cell1", "Cell2", "Cell3"])]; -/// let widths = [Constraint::Length(5), Constraint::Length(5), Constraint::Length(10)]; +/// let widths = [ +/// Constraint::Length(5), +/// Constraint::Length(5), +/// Constraint::Length(10), +/// ]; /// let table = Table::new(rows, widths).red().italic(); /// ``` /// @@ -236,6 +237,7 @@ pub struct Table<'a> { /// /// ```rust /// use std::borrow::Cow; +/// /// use ratatui::{prelude::*, widgets::*}; /// /// Row::new(vec![ @@ -273,13 +275,14 @@ pub struct Row<'a> { /// /// ```rust /// use std::borrow::Cow; +/// /// use ratatui::{prelude::*, widgets::*}; /// /// Cell::from("simple string"); /// Cell::from(Span::from("span")); /// Cell::from(Line::from(vec![ /// Span::raw("a vec of "), -/// Span::styled("spans", Style::default().add_modifier(Modifier::BOLD)) +/// Span::styled("spans", Style::default().add_modifier(Modifier::BOLD)), /// ])); /// Cell::from(Text::from("a text")); /// Cell::from(Text::from(Cow::Borrowed("hello"))); @@ -355,7 +358,7 @@ pub enum HighlightSpacing { /// // method) so that the selected row is preserved across renders /// let mut table_state = TableState::default(); /// *table_state.offset_mut() = 1; // display the second row and onwards -/// table_state.select(Some(3)); // select the forth row (0-indexed) +/// table_state.select(Some(3)); // select the forth row (0-indexed) /// /// frame.render_stateful_widget(table, area, &mut table_state); /// # } @@ -445,7 +448,10 @@ impl<'a> Table<'a> { /// /// ```rust /// # use ratatui::{prelude::*, widgets::*}; - /// let header = Row::new(vec![Cell::from("Header Cell 1"), Cell::from("Header Cell 2")]); + /// let header = Row::new(vec![ + /// Cell::from("Header Cell 1"), + /// Cell::from("Header Cell 2"), + /// ]); /// let table = Table::default().header(header); /// ``` #[must_use = "method moves the value of self and returns the modified value"] @@ -669,7 +675,11 @@ impl<'a> Row<'a> { /// ```rust /// # use ratatui::{prelude::*, widgets::*}; /// let row = Row::new(vec!["Cell 1", "Cell 2", "Cell 3"]); - /// let row = Row::new(vec![Cell::new("Cell 1"), Cell::new("Cell 2"), Cell::new("Cell 3")]); + /// let row = Row::new(vec![ + /// Cell::new("Cell 1"), + /// Cell::new("Cell 2"), + /// Cell::new("Cell 3"), + /// ]); /// ``` pub fn new(cells: T) -> Self where @@ -695,7 +705,11 @@ impl<'a> Row<'a> { /// ```rust /// # use ratatui::{prelude::*, widgets::*}; /// let row = Row::default().cells(vec!["Cell 1", "Cell 2", "Cell 3"]); - /// let row = Row::default().cells(vec![Cell::new("Cell 1"), Cell::new("Cell 2"), Cell::new("Cell 3")]); + /// let row = Row::default().cells(vec![ + /// Cell::new("Cell 1"), + /// Cell::new("Cell 2"), + /// Cell::new("Cell 3"), + /// ]); /// ``` #[must_use = "method moves the value of self and returns the modified value"] pub fn cells(mut self, cells: T) -> Self @@ -790,7 +804,7 @@ impl<'a> Cell<'a> { /// Cell::new(Span::from("span")); /// Cell::new(Line::from(vec![ /// Span::raw("a vec of "), - /// Span::styled("spans", Style::default().add_modifier(Modifier::BOLD)) + /// Span::styled("spans", Style::default().add_modifier(Modifier::BOLD)), /// ])); /// Cell::new(Text::from("a text")); /// ``` @@ -818,7 +832,7 @@ impl<'a> Cell<'a> { /// Cell::default().content(Span::from("span")); /// Cell::default().content(Line::from(vec![ /// Span::raw("a vec of "), - /// Span::styled("spans", Style::new().bold()) + /// Span::styled("spans", Style::new().bold()), /// ])); /// Cell::default().content(Text::from("a text")); /// ```