From e098731d6c1a68a0319d544301ac91cf2d05ccb2 Mon Sep 17 00:00:00 2001 From: Valentin271 <36198422+Valentin271@users.noreply.github.com> Date: Sat, 2 Sep 2023 04:59:35 +0200 Subject: [PATCH] docs(barchart): add documentation to `BarChart` (#449) Add documentation to the `BarChart` widgets and its sub-modules. --- src/widgets/barchart/bar.rs | 55 +++++++++-- src/widgets/barchart/bar_group.rs | 5 +- src/widgets/barchart/mod.rs | 151 +++++++++++++++++++++++++++--- 3 files changed, 187 insertions(+), 24 deletions(-) diff --git a/src/widgets/barchart/bar.rs b/src/widgets/barchart/bar.rs index 0184ff42..49b19e63 100644 --- a/src/widgets/barchart/bar.rs +++ b/src/widgets/barchart/bar.rs @@ -1,11 +1,19 @@ use crate::{buffer::Buffer, prelude::Rect, style::Style, text::Line}; -/// represent a bar to be shown by the Barchart +/// A bar to be shown by the [`BarChart`](crate::widgets::BarChart) widget. /// -/// # Examples -/// the following example creates a bar with the label "Bar 1", a value "10", -/// red background and a white value foreground +/// Here is an explanation of a `Bar`'s components. +/// ```plain +/// ███ ┐ +/// █2█ <- text_value or value │ bar +/// foo <- label ┘ +/// ``` +/// Note that every element can be styled individually. /// +/// # Example +/// +/// The following example creates a bar with the label "Bar 1", a value "10", +/// red background and a white value foreground. /// ``` /// # use ratatui::{prelude::*, widgets::*}; /// Bar::default() @@ -30,34 +38,67 @@ pub struct Bar<'a> { } impl<'a> Bar<'a> { + /// Set the value of this bar. + /// + /// The value will be displayed inside the bar. + /// + /// # See also + /// + /// [`Bar::value_style`] to style the value. + /// [`Bar::text_value`] to set the displayed value. pub fn value(mut self, value: u64) -> Bar<'a> { self.value = value; self } + /// Set the label of the bar. + /// + /// For [`Vertical`](crate::layout::Direction::Vertical) bars, + /// display the label **under** the bar. + /// For [`Horizontal`](crate::layout::Direction::Horizontal) bars, + /// display the label **in** the bar. + /// See [`BarChart::direction`](crate::widgets::BarChart::direction) to set the direction. pub fn label(mut self, label: Line<'a>) -> Bar<'a> { self.label = Some(label); self } + /// Set the style of the bar. + /// + /// This will apply to every non-styled element. + /// It can be seen and used as a default value. pub fn style(mut self, style: Style) -> Bar<'a> { self.style = style; self } + /// Set the style of the value. + /// + /// # See also + /// + /// [`Bar::value`] to set the value. pub fn value_style(mut self, style: Style) -> Bar<'a> { self.value_style = style; self } - /// set the text value printed in the bar. (By default self.value is printed) + /// Set the text value printed in the bar. + /// + /// If `text_value` is not set, then the [ToString] representation of `value` will be shown on + /// the bar. + /// + /// # See also + /// + /// [`Bar::value`] to set the value. pub fn text_value(mut self, text_value: String) -> Bar<'a> { self.text_value = Some(text_value); self } - /// Render the value of the bar. value_text is used if set, otherwise the value is converted to - /// string. The value is rendered using value_style. If the value width is greater than the + /// Render the value of the bar. + /// + /// [`text_value`](Bar::text_value) is used if set, otherwise the value is converted to string. + /// The value is rendered using value_style. If the value width is greater than the /// bar width, then the value is split into 2 parts. the first part is rendered in the bar /// using value_style. The second part is rendered outside the bar using bar_style pub(super) fn render_value_with_different_styles( diff --git a/src/widgets/barchart/bar_group.rs b/src/widgets/barchart/bar_group.rs index 7b65a93e..1bbba70d 100644 --- a/src/widgets/barchart/bar_group.rs +++ b/src/widgets/barchart/bar_group.rs @@ -5,9 +5,10 @@ use crate::{ text::Line, }; -/// represent a group of bars to be shown by the Barchart +/// A group of bars to be shown by the Barchart. /// /// # Examples +/// /// ``` /// # use ratatui::{prelude::*, widgets::*}; /// BarGroup::default() @@ -35,7 +36,7 @@ impl<'a> BarGroup<'a> { self } - /// return the maximum bar value of this group + /// The maximum bar value of this group pub(super) fn max(&self) -> Option { self.bars.iter().max_by_key(|v| v.value).map(|v| v.value) } diff --git a/src/widgets/barchart/mod.rs b/src/widgets/barchart/mod.rs index 0739790a..7cfbcee8 100644 --- a/src/widgets/barchart/mod.rs +++ b/src/widgets/barchart/mod.rs @@ -1,3 +1,4 @@ +#![warn(missing_docs)] use crate::prelude::*; mod bar; @@ -8,14 +9,41 @@ pub use bar_group::BarGroup; use super::{Block, Widget}; -/// Display multiple bars in a single widgets +/// A chart showing values as [bars](Bar). +/// +/// Here is a possible `BarChart` output. +/// ```plain +/// ┌─────────────────────────────────┐ +/// │ ████│ +/// │ ▅▅▅▅ ████│ +/// │ ▇▇▇▇ ████ ████│ +/// │ ▄▄▄▄ ████ ████ ████ ████│ +/// │▆10▆ █20█ █50█ █40█ █60█ █90█│ +/// │ B1 B2 B1 B2 B1 B2 │ +/// │ Group1 Group2 Group3 │ +/// └─────────────────────────────────┘ +/// ``` +/// +/// A `BarChart` is composed of a set of [`Bar`] which can be set via [`BarChart::data`]. +/// Bars can be styled globally ([`BarChart::bar_style`]) or individually ([`Bar::style`]). +/// There are other methods available to style even more precisely. See [`Bar`] to find out about +/// each bar component. +/// +/// The `BarChart` widget can also show groups of bars via [`BarGroup`]. +/// A [`BarGroup`] is a set of [`Bar`], multiple can be added to a `BarChart` using +/// [`BarChart::data`] multiple time as demonstrated in the example below. +/// +/// The chart can have a [`Direction`] (by default the bars are [`Vertical`](Direction::Vertical)). +/// This is set using [`BarChart::direction`]. /// /// # Examples -/// The following example creates a BarChart with two groups of bars. -/// The first group is added by an array slice (&[(&str, u64)]). -/// The second group is added by a slice of Groups (&[BarGroup]). +/// +/// The following example creates a `BarChart` with two groups of bars. +/// The first group is added by an array slice (`&[(&str, u64)]`). +/// The second group is added by a [`BarGroup`] instance. /// ``` -/// # use ratatui::{prelude::*, widgets::*}; +/// use ratatui::{prelude::*, widgets::*}; +/// /// BarChart::default() /// .block(Block::default().title("BarChart").borders(Borders::ALL)) /// .bar_width(3) @@ -78,16 +106,18 @@ impl<'a> Default for BarChart<'a> { impl<'a> BarChart<'a> { /// Add group of bars to the BarChart + /// /// # Examples - /// The following example creates a BarChart with two groups of bars. - /// The first group is added by an array slice (&[(&str, u64)]). - /// The second group is added by a BarGroup instance. + /// + /// The following example creates a BarChart with two groups of bars. + /// The first group is added by an array slice (`&[(&str, u64)]`). + /// The second group is added by a [`BarGroup`] instance. /// ``` - /// # use ratatui::{prelude::*, widgets::*}; + /// use ratatui::{prelude::*, widgets::*}; /// /// BarChart::default() - /// .data(&[("B0", 0), ("B1", 2), ("B2", 4), ("B3", 3)]) - /// .data(BarGroup::default().bars(&[Bar::default().value(10), Bar::default().value(20)])); + /// .data(&[("B0", 0), ("B1", 2), ("B2", 4), ("B3", 3)]) + /// .data(BarGroup::default().bars(&[Bar::default().value(10), Bar::default().value(20)])); /// ``` pub fn data(mut self, data: impl Into>) -> BarChart<'a> { let group: BarGroup = data.into(); @@ -97,66 +127,157 @@ impl<'a> BarChart<'a> { self } + /// Surround the [`BarChart`] with a [`Block`]. pub fn block(mut self, block: Block<'a>) -> BarChart<'a> { self.block = Some(block); self } + /// Set the value necessary for a [`Bar`] to reach the maximum height. + /// + /// If not set, the maximum value in the data is taken as reference. + /// + /// # Examples + /// + /// This example shows the default behavior when `max` is not set. + /// The maximum value in the dataset is taken (here, `100`). + /// ``` + /// # use ratatui::widgets::BarChart; + /// BarChart::default().data(&[("foo", 1), ("bar", 2), ("baz", 100)]); + /// // Renders + /// // █ + /// // █ + /// // f b b + /// ``` + /// + /// This example shows a custom max value. + /// The maximum height being `2`, `bar` & `baz` render as the max. + /// ``` + /// # use ratatui::widgets::BarChart; + /// BarChart::default() + /// .data(&[("foo", 1), ("bar", 2), ("baz", 100)]) + /// .max(2); + /// // Renders + /// // █ █ + /// // █ █ █ + /// // f b b + /// ``` pub fn max(mut self, max: u64) -> BarChart<'a> { self.max = Some(max); self } /// Set the default style of the bar. - /// It is also possible to set individually the style of each Bar. + /// + /// 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 pub fn bar_style(mut self, style: Style) -> BarChart<'a> { self.bar_style = style; self } + /// Set the width of the displayed bars. + /// + /// For [`Horizontal`](crate::layout::Direction::Horizontal) bars this becomes the height of + /// the bar. + /// + /// If not set, this defaults to `1`. + /// The bar label also uses this value as its width. pub fn bar_width(mut self, width: u16) -> BarChart<'a> { self.bar_width = width; self } + /// Set the gap between each bar. + /// + /// If not set, this defaults to `1`. + /// The bar label will never be larger than the bar itself, even if the gap is sufficient. + /// + /// # Example + /// + /// This shows two bars with a gap of `3`. Notice the labels will always stay under the bar. + /// ``` + /// # use ratatui::widgets::BarChart; + /// BarChart::default() + /// .data(&[("foo", 1), ("bar", 2)]) + /// .bar_gap(3); + /// // Renders + /// // █ + /// // █ █ + /// // f b + /// ``` pub fn bar_gap(mut self, gap: u16) -> BarChart<'a> { self.bar_gap = gap; self } + /// 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). pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> BarChart<'a> { self.bar_set = bar_set; self } /// Set the default value style of the bar. - /// It is also possible to set individually the value style of each Bar. + /// + /// It is also possible to set individually the value style of each [`Bar`]. /// In this case the default value style will be patched by the individual value style + /// + /// # See also + /// + /// [Bar::value_style] to set the value style individually. pub fn value_style(mut self, style: Style) -> BarChart<'a> { self.value_style = style; self } /// Set the default label style of the groups and bars. - /// It is also possible to set individually the label style of each Bar or Group. + /// + /// It is also possible to set individually the label style of each [`Bar`] or [`BarGroup`]. /// In this case the default label style will be patched by the individual label style + /// + /// # See also + /// + /// [Bar::label] to set the label style individually. pub fn label_style(mut self, style: Style) -> BarChart<'a> { self.label_style = style; self } + /// Set the gap between [`BarGroup`]. pub fn group_gap(mut self, gap: u16) -> BarChart<'a> { self.group_gap = gap; self } + /// Set the style of the entire chart. + /// + /// The style will be applied to everything that isn't styled (borders, bars, labels, ...). pub fn style(mut self, style: Style) -> BarChart<'a> { self.style = style; self } - /// Set the direction of the bars + /// Set the direction of the bars. + /// + /// [`Vertical`](crate::layout::Direction::Vertical) bars are the default. + /// + /// # Examples + /// + /// Vertical bars + /// ```plain + /// █ + /// █ █ + /// f b + /// ``` + /// + /// Horizontal bars + /// ```plain + /// █foo██ + /// + /// █bar██ + /// ``` pub fn direction(mut self, direction: Direction) -> BarChart<'a> { self.direction = direction; self