From fe632d70cb150264d9af2f79145a1d14a3637f3e Mon Sep 17 00:00:00 2001
From: Valentin271 <36198422+Valentin271@users.noreply.github.com>
Date: Mon, 27 Nov 2023 00:46:20 +0100
Subject: [PATCH] docs(Sparkline): add documentation (#648)

---
 src/widgets/sparkline.rs | 48 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/src/widgets/sparkline.rs b/src/widgets/sparkline.rs
index 47fa86e7..282aa271 100644
--- a/src/widgets/sparkline.rs
+++ b/src/widgets/sparkline.rs
@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 use std::cmp::min;
 
 use strum::{Display, EnumString};
@@ -12,6 +13,18 @@ use crate::{
 
 /// Widget to render a sparkline over one or more lines.
 ///
+/// You can create a `Sparkline` using [`Sparkline::default`].
+///
+/// `Sparkline` can be styled either using [`Sparkline::style`] or preferably using the methods
+/// provided by the [`Stylize`](crate::style::Stylize) trait.
+///
+/// # Builder methods
+///
+/// - [`Sparkline::block`] wraps the sparkline in a [`Block`]
+/// - [`Sparkline::data`] defines the dataset, you'll almost always want to use it
+/// - [`Sparkline::max`] sets the maximum value of bars
+/// - [`Sparkline::direction`] sets the render direction
+///
 /// # Examples
 ///
 /// ```
@@ -21,7 +34,8 @@ use crate::{
 ///     .block(Block::default().title("Sparkline").borders(Borders::ALL))
 ///     .data(&[0, 2, 3, 4, 1, 4, 10])
 ///     .max(5)
-///     .style(Style::default().fg(Color::Red).bg(Color::White));
+///     .direction(RenderDirection::RightToLeft)
+///     .style(Style::default().red().on_white());
 /// ```
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct Sparkline<'a> {
@@ -40,10 +54,15 @@ pub struct Sparkline<'a> {
     direction: RenderDirection,
 }
 
+/// Defines the direction in which sparkline will be rendered.
+///
+/// See [`Sparkline::direction`].
 #[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
 pub enum RenderDirection {
+    /// The first value is on the left, going to the right
     #[default]
     LeftToRight,
+    /// The first value is on the right, going to the left
     RightToLeft,
 }
 
@@ -61,31 +80,58 @@ impl<'a> Default for Sparkline<'a> {
 }
 
 impl<'a> Sparkline<'a> {
+    /// Wraps the sparkline with the given `block`.
     pub fn block(mut self, block: Block<'a>) -> Sparkline<'a> {
         self.block = Some(block);
         self
     }
 
+    /// Sets the style of the entire widget.
+    ///
+    /// The foreground corresponds to the bars while the background is everything else.
     pub fn style(mut self, style: Style) -> Sparkline<'a> {
         self.style = style;
         self
     }
 
+    /// Sets the dataset for the sparkline.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// # fn ui(frame: &mut Frame) {
+    /// # let area = Rect::default();
+    /// let sparkline = Sparkline::default().data(&[1, 2, 3]);
+    /// frame.render_widget(sparkline, area);
+    /// # }
+    /// ```
     pub fn data(mut self, data: &'a [u64]) -> Sparkline<'a> {
         self.data = data;
         self
     }
 
+    /// Sets the maximum value of bars.
+    ///
+    /// Every bar will be scaled accordingly. If no max is given, this will be the max in the
+    /// dataset.
     pub fn max(mut self, max: u64) -> Sparkline<'a> {
         self.max = Some(max);
         self
     }
 
+    /// Sets the characters used to display the bars.
+    ///
+    /// Can be [`symbols::bar::THREE_LEVELS`], [`symbols::bar::NINE_LEVELS`] (default) or a custom
+    /// [`Set`](symbols::bar::Set).
     pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> Sparkline<'a> {
         self.bar_set = bar_set;
         self
     }
 
+    /// Sets the direction of the sparkline.
+    ///
+    /// [`RenderDirection::LeftToRight`] by default.
     pub fn direction(mut self, direction: RenderDirection) -> Sparkline<'a> {
         self.direction = direction;
         self