doc(style): improve documentation of Style

Author: fdehau

src/style.rs

@@ -1,3 +1,5 @@
+//! `style` contains the primitives used to control how your user interface will look.
+
 use bitflags::bitflags;
 
 #[derive(Debug, Clone, Copy, PartialEq)]
@@ -25,6 +27,17 @@ pub enum Color {
 }
 
 bitflags! {
+    /// Modifier changes the way a piece of text is displayed.
+    ///
+    /// They are bitflags so they can easily be composed.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// # use tui::style::Modifier;
+    ///
+    /// let m = Modifier::BOLD | Modifier::ITALIC;
+    /// ```
     #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
     pub struct Modifier: u16 {
         const BOLD              = 0b0000_0000_0001;
@@ -39,11 +52,32 @@ bitflags! {
     }
 }
 
+/// Style let you control the main characteristics of the displayed elements.
+///
+/// ## Examples
+///
+/// ```rust
+/// # use tui::style::{Color, Modifier, Style};
+/// // Using the raw struct initialization:
+/// let s = Style {
+///     fg: Color::Black,
+///     bg: Color::Green,
+///     modifier: Modifier::ITALIC | Modifier::BOLD
+/// };
+/// // Using the provided builder pattern:
+/// let s = Style::default()
+///     .fg(Color::Black)
+///     .bg(Color::Green)
+///     .modifier(Modifier::ITALIC | Modifier::BOLD);
+/// ```
 #[derive(Debug, Clone, Copy, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Style {
+    /// The foreground color.
     pub fg: Color,
+    /// The background color.
     pub bg: Color,
+    /// The emphasis applied to the text graphemes.
     pub modifier: Modifier,
 }
 
@@ -61,20 +95,63 @@ impl Style {
             modifier: Modifier::empty(),
         }
     }
+
+    /// Reinitializes the style properties. Both colors are put back to `Color::Reset` while
+    /// all modifiers are cleared.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// # use tui::style::{Color, Modifier, Style};
+    /// let mut s = Style::default().fg(Color::Red).bg(Color::Green).modifier(Modifier::BOLD);
+    /// s.reset();
+    /// assert_eq!(s.fg, Color::Reset);
+    /// assert_eq!(s.bg, Color::Reset);
+    /// assert_eq!(s.modifier, Modifier::empty());
+    /// ```
     pub fn reset(&mut self) {
         self.fg = Color::Reset;
         self.bg = Color::Reset;
         self.modifier = Modifier::empty();
     }
 
+    /// Changes the foreground color.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// # use tui::style::{Color, Style};
+    /// let s = Style::default().fg(Color::Red);
+    /// assert_eq!(s.fg, Color::Red);
+    /// ```
     pub const fn fg(mut self, color: Color) -> Style {
         self.fg = color;
         self
     }
+
+    /// Changes the background color.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// # use tui::style::{Color, Style};
+    /// let s = Style::default().bg(Color::Red);
+    /// assert_eq!(s.bg, Color::Red);
+    /// ```
     pub const fn bg(mut self, color: Color) -> Style {
         self.bg = color;
         self
     }
+
+    /// Changes the emphasis.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// # use tui::style::{Modifier, Style};
+    /// let s = Style::default().modifier(Modifier::BOLD | Modifier::ITALIC);
+    /// assert_eq!(s.modifier, Modifier::BOLD | Modifier::ITALIC);
+    /// ```
     pub const fn modifier(mut self, modifier: Modifier) -> Style {
         self.modifier = modifier;
         self