Write documentation for `iced_style`

2 files changed, 120 insertions, 42 deletions

diff --git a/style/src/theme.rs b/style/src/theme.rs
index ca2d1904..d7ebb827 100644
--- a/style/src/theme.rs
+++ b/style/src/theme.rs
@@ -1,3 +1,4 @@
+//! Use the built-in theme and styles.
 pub mod palette;
 
 use self::palette::Extended;
@@ -23,19 +24,25 @@ use iced_core::{Background, Color, Vector};
 
 use std::rc::Rc;
 
+/// A built-in theme.
 #[derive(Debug, Clone, PartialEq, Default)]
 pub enum Theme {
+    /// The built-in light variant.
     #[default]
     Light,
+    /// The built-in dark variant.
     Dark,
+    /// A [`Theme`] that uses a [`Custom`] palette.
     Custom(Box<Custom>),
 }
 
 impl Theme {
+    /// Creates a new custom [`Theme`] from the given [`Palette`].
     pub fn custom(palette: Palette) -> Self {
         Self::Custom(Box::new(Custom::new(palette)))
     }
 
+    /// Returns the [`Palette`] of the [`Theme`].
     pub fn palette(&self) -> Palette {
         match self {
             Self::Light => Palette::LIGHT,
@@ -44,6 +51,7 @@ impl Theme {
         }
     }
 
+    /// Returns the [`palette::Extended`] of the [`Theme`].
     pub fn extended_palette(&self) -> &palette::Extended {
         match self {
             Self::Light => &palette::EXTENDED_LIGHT,
@@ -53,6 +61,7 @@ impl Theme {
     }
 }
 
+/// A [`Theme`] with a customized [`Palette`].
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Custom {
     palette: Palette,
@@ -60,6 +69,7 @@ pub struct Custom {
 }
 
 impl Custom {
+    /// Creates a [`Custom`] theme from the given [`Palette`].
     pub fn new(palette: Palette) -> Self {
         Self {
             palette,
@@ -68,10 +78,13 @@ impl Custom {
     }
 }
 
+/// The style of an application.
 #[derive(Default)]
 pub enum Application {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Box<dyn application::StyleSheet<Style = Theme>>),
 }
 
@@ -105,17 +118,23 @@ impl From<fn(&Theme) -> application::Appearance> for Application {
     }
 }
 
-/*
- * Button
- */
+/// The style of a button.
 #[derive(Default)]
 pub enum Button {
+    /// The primary style.
     #[default]
     Primary,
+    /// The secondary style.
     Secondary,
+    /// The positive style.
     Positive,
+    /// The destructive style.
     Destructive,
+    /// The text style.
+    ///
+    /// Useful for links!
     Text,
+    /// A custom style.
     Custom(Box<dyn button::StyleSheet<Style = Theme>>),
 }
 
@@ -207,16 +226,19 @@ impl button::StyleSheet for Theme {
     }
 }
 
-/*
- * Checkbox
- */
+/// The style of a checkbox.
 #[derive(Default)]
 pub enum Checkbox {
+    /// The primary style.
     #[default]
     Primary,
+    /// The secondary style.
     Secondary,
+    /// The success style.
     Success,
+    /// The danger style.
     Danger,
+    /// A custom style.
     Custom(Box<dyn checkbox::StyleSheet<Style = Theme>>),
 }
 
@@ -316,14 +338,15 @@ fn checkbox_appearance(
     }
 }
 
-/*
- * Container
- */
+/// The style of a container.
 #[derive(Default)]
 pub enum Container {
+    /// No style.
     #[default]
     Transparent,
+    /// A simple box.
     Box,
+    /// A custom style.
     Custom(Box<dyn container::StyleSheet<Style = Theme>>),
 }
 
@@ -363,13 +386,13 @@ impl container::StyleSheet for fn(&Theme) -> container::Appearance {
     }
 }
 
-/*
- * Slider
- */
+/// The style of a slider.
 #[derive(Default)]
 pub enum Slider {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Box<dyn slider::StyleSheet<Style = Theme>>),
 }
 
@@ -444,13 +467,13 @@ impl slider::StyleSheet for Theme {
     }
 }
 
-/*
- * Menu
- */
+/// The style of a menu.
 #[derive(Clone, Default)]
 pub enum Menu {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Rc<dyn menu::StyleSheet<Style = Theme>>),
 }
 
@@ -486,13 +509,13 @@ impl From<PickList> for Menu {
     }
 }
 
-/*
- * Pick List
- */
+/// The style of a pick list.
 #[derive(Clone, Default)]
 pub enum PickList {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(
         Rc<dyn pick_list::StyleSheet<Style = Theme>>,
         Rc<dyn menu::StyleSheet<Style = Theme>>,
@@ -541,13 +564,13 @@ impl pick_list::StyleSheet for Theme {
     }
 }
 
-/*
- * Radio
- */
+/// The style of a radio button.
 #[derive(Default)]
 pub enum Radio {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Box<dyn radio::StyleSheet<Style = Theme>>),
 }
 
@@ -596,13 +619,13 @@ impl radio::StyleSheet for Theme {
     }
 }
 
-/*
- * Toggler
- */
+/// The style of a toggler.
 #[derive(Default)]
 pub enum Toggler {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Box<dyn toggler::StyleSheet<Style = Theme>>),
 }
 
@@ -663,13 +686,13 @@ impl toggler::StyleSheet for Theme {
     }
 }
 
-/*
- * Pane Grid
- */
+/// The style of a pane grid.
 #[derive(Default)]
 pub enum PaneGrid {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Box<dyn pane_grid::StyleSheet<Style = Theme>>),
 }
 
@@ -705,15 +728,17 @@ impl pane_grid::StyleSheet for Theme {
     }
 }
 
-/*
- * Progress Bar
- */
+/// The style of a progress bar.
 #[derive(Default)]
 pub enum ProgressBar {
+    /// The primary style.
     #[default]
     Primary,
+    /// The success style.
     Success,
+    /// The danger style.
     Danger,
+    /// A custom style.
     Custom(Box<dyn progress_bar::StyleSheet<Style = Theme>>),
 }
 
@@ -756,13 +781,13 @@ impl progress_bar::StyleSheet for fn(&Theme) -> progress_bar::Appearance {
     }
 }
 
-/*
- * Rule
- */
+/// The style of a rule.
 #[derive(Default)]
 pub enum Rule {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Box<dyn rule::StyleSheet<Style = Theme>>),
 }
 
@@ -798,13 +823,13 @@ impl rule::StyleSheet for fn(&Theme) -> rule::Appearance {
     }
 }
 
-/*
- * Scrollable
- */
+/// The style of a scrollable.
 #[derive(Default)]
 pub enum Scrollable {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Box<dyn scrollable::StyleSheet<Style = Theme>>),
 }
 
@@ -863,13 +888,13 @@ impl scrollable::StyleSheet for Theme {
     }
 }
 
-/*
- * Text
- */
+/// The style of text.
 #[derive(Clone, Copy, Default)]
 pub enum Text {
+    /// The default style.
     #[default]
     Default,
+    /// Colored text.
     Color(Color),
 }
 
@@ -890,13 +915,13 @@ impl text::StyleSheet for Theme {
     }
 }
 
-/*
- * Text Input
- */
+/// The style of a text input.
 #[derive(Default)]
 pub enum TextInput {
+    /// The default style.
     #[default]
     Default,
+    /// A custom style.
     Custom(Box<dyn text_input::StyleSheet<Style = Theme>>),
 }
 
diff --git a/style/src/theme/palette.rs b/style/src/theme/palette.rs
index b3a10d28..0f15494b 100644
--- a/style/src/theme/palette.rs
+++ b/style/src/theme/palette.rs
@@ -1,18 +1,26 @@
+//! Define the colors of a theme.
 use iced_core::Color;
 
 use once_cell::sync::Lazy;
 use palette::{FromColor, Hsl, Mix, RelativeContrast, Srgb};
 
+/// A color palette.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Palette {
+    /// The background [`Color`] of the [`Palette`].
     pub background: Color,
+    /// The text [`Color`] of the [`Palette`].
     pub text: Color,
+    /// The primary [`Color`] of the [`Palette`].
     pub primary: Color,
+    /// The success [`Color`] of the [`Palette`].
     pub success: Color,
+    /// The danger [`Color`] of the [`Palette`].
     pub danger: Color,
 }
 
 impl Palette {
+    /// The built-in light variant of a [`Palette`].
     pub const LIGHT: Self = Self {
         background: Color::WHITE,
         text: Color::BLACK,
@@ -33,6 +41,7 @@ impl Palette {
         ),
     };
 
+    /// The built-in dark variant of a [`Palette`].
     pub const DARK: Self = Self {
         background: Color::from_rgb(
             0x20 as f32 / 255.0,
@@ -58,21 +67,31 @@ impl Palette {
     };
 }
 
+/// An extended set of colors generated from a [`Palette`].
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Extended {
+    /// The set of background colors.
     pub background: Background,
+    /// The set of primary colors.
     pub primary: Primary,
+    /// The set of secondary colors.
     pub secondary: Secondary,
+    /// The set of success colors.
     pub success: Success,
+    /// The set of danger colors.
     pub danger: Danger,
 }
 
+/// The built-in light variant of an [`Extended`] palette.
 pub static EXTENDED_LIGHT: Lazy<Extended> =
     Lazy::new(|| Extended::generate(Palette::LIGHT));
+
+/// The built-in dark variant of an [`Extended`] palette.
 pub static EXTENDED_DARK: Lazy<Extended> =
     Lazy::new(|| Extended::generate(Palette::DARK));
 
 impl Extended {
+    /// Generates an [`Extended`] palette from a simple [`Palette`].
     pub fn generate(palette: Palette) -> Self {
         Self {
             background: Background::new(palette.background, palette.text),
@@ -96,13 +115,22 @@ impl Extended {
     }
 }
 
+/// A pair of background and text colors.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Pair {
+    /// The background color.
     pub color: Color,
+
+    /// The text color.
+    ///
+    /// It's guaranteed to be readable on top of the background [`color`].
+    ///
+    /// [`color`]: Self::color
     pub text: Color,
 }
 
 impl Pair {
+    /// Creates a new [`Pair`] from a background [`Color`] and some text [`Color`].
     pub fn new(color: Color, text: Color) -> Self {
         Self {
             color,
@@ -111,14 +139,19 @@ impl Pair {
     }
 }
 
+/// A set of background colors.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Background {
+    /// The base background color.
     pub base: Pair,
+    /// A weaker version of the base background color.
     pub weak: Pair,
+    /// A stronger version of the base background color.
     pub strong: Pair,
 }
 
 impl Background {
+    /// Generates a set of [`Background`] colors from the base and text colors.
     pub fn new(base: Color, text: Color) -> Self {
         let weak = mix(base, text, 0.15);
         let strong = mix(base, text, 0.40);
@@ -131,14 +164,19 @@ impl Background {
     }
 }
 
+/// A set of primary colors.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Primary {
+    /// The base primary color.
     pub base: Pair,
+    /// A weaker version of the base primary color.
     pub weak: Pair,
+    /// A stronger version of the base primary color.
     pub strong: Pair,
 }
 
 impl Primary {
+    /// Generates a set of [`Primary`] colors from the base, background, and text colors.
     pub fn generate(base: Color, background: Color, text: Color) -> Self {
         let weak = mix(base, background, 0.4);
         let strong = deviate(base, 0.1);
@@ -151,14 +189,19 @@ impl Primary {
     }
 }
 
+/// A set of secondary colors.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Secondary {
+    /// The base secondary color.
     pub base: Pair,
+    /// A weaker version of the base secondary color.
     pub weak: Pair,
+    /// A stronger version of the base secondary color.
     pub strong: Pair,
 }
 
 impl Secondary {
+    /// Generates a set of [`Secondary`] colors from the base and text colors.
     pub fn generate(base: Color, text: Color) -> Self {
         let base = mix(base, text, 0.2);
         let weak = mix(base, text, 0.1);
@@ -172,14 +215,19 @@ impl Secondary {
     }
 }
 
+/// A set of success colors.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Success {
+    /// The base success color.
     pub base: Pair,
+    /// A weaker version of the base success color.
     pub weak: Pair,
+    /// A stronger version of the base success color.
     pub strong: Pair,
 }
 
 impl Success {
+    /// Generates a set of [`Success`] colors from the base, background, and text colors.
     pub fn generate(base: Color, background: Color, text: Color) -> Self {
         let weak = mix(base, background, 0.4);
         let strong = deviate(base, 0.1);
@@ -192,14 +240,19 @@ impl Success {
     }
 }
 
+/// A set of danger colors.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Danger {
+    /// The base danger color.
     pub base: Pair,
+    /// A weaker version of the base danger color.
     pub weak: Pair,
+    /// A stronger version of the base danger color.
     pub strong: Pair,
 }
 
 impl Danger {
+    /// Generates a set of [`Danger`] colors from the base, background, and text colors.
     pub fn generate(base: Color, background: Color, text: Color) -> Self {
         let weak = mix(base, background, 0.4);
         let strong = deviate(base, 0.1);