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
ratatui · Dec 16, 2023 · 910ad00 · 910ad00
1 parent b282a06
commit 910ad00
Show file tree

Hide file tree

Showing 24 changed files with 285 additions and 173 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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<I>(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<I>(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<T>(lengths: T) -> Vec<Constraint>
     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<T>(ratios: T) -> Vec<Constraint>
     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<T>(percentages: T) -> Vec<Constraint>
     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<T>(maxes: T) -> Vec<Constraint>
     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<T>(mins: T) -> Vec<Constraint>
     where

diff --git 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
@@ -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
@@ -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
@@ -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"]