Start documenting Theme crate

Co-Authored-By: Antonio Scandurra <me@as-cii.com>

crates/theme/src/scale.rs

@@ -2,41 +2,31 @@ use gpui::{AppContext, Hsla, SharedString};
 
 use crate::{ActiveTheme, Appearance};
 
-/// A one-based step in a [`ColorScale`].
+/// A collection of colors that are used to style the UI.
+///
+/// Each step has a semantic meaning, and is used to style different parts of the UI.
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy)]
 pub struct ColorScaleStep(usize);
 
 impl ColorScaleStep {
-    pub const ONE: Self = Self(1);
-    pub const TWO: Self = Self(2);
-    pub const THREE: Self = Self(3);
-    pub const FOUR: Self = Self(4);
-    pub const FIVE: Self = Self(5);
-    pub const SIX: Self = Self(6);
-    pub const SEVEN: Self = Self(7);
-    pub const EIGHT: Self = Self(8);
-    pub const NINE: Self = Self(9);
-    pub const TEN: Self = Self(10);
-    pub const ELEVEN: Self = Self(11);
-    pub const TWELVE: Self = Self(12);
-
-    /// All of the steps in a [`ColorScale`].
-    pub const ALL: [ColorScaleStep; 12] = [
-        Self::ONE,
-        Self::TWO,
-        Self::THREE,
-        Self::FOUR,
-        Self::FIVE,
-        Self::SIX,
-        Self::SEVEN,
-        Self::EIGHT,
-        Self::NINE,
-        Self::TEN,
-        Self::ELEVEN,
-        Self::TWELVE,
-    ];
+    const ONE: Self = Self(1);
+    const TWO: Self = Self(2);
+    const THREE: Self = Self(3);
+    const FOUR: Self = Self(4);
+    const FIVE: Self = Self(5);
+    const SIX: Self = Self(6);
+    const SEVEN: Self = Self(7);
+    const EIGHT: Self = Self(8);
+    const NINE: Self = Self(9);
+    const TEN: Self = Self(10);
+    const ELEVEN: Self = Self(11);
+    const TWELVE: Self = Self(12);
 }
 
+/// A scale of colors for a given [ColorScaleSet].
+///
+/// Each [ColorScale] contains exactly 12 colors. Refer to
+/// [ColorScaleStep] for a reference of what each step is used for.
 pub struct ColorScale(Vec<Hsla>);
 
 impl FromIterator<Hsla> for ColorScale {
@@ -229,6 +219,7 @@ impl IntoIterator for ColorScales {
     }
 }
 
+/// Provides groups of [ColorScale]s for light and dark themes, as well as transparent versions of each scale.
 pub struct ColorScaleSet {
     name: SharedString,
     light: ColorScale,

crates/theme/src/settings.rs

@@ -27,7 +27,7 @@ pub struct ThemeSettings {
 }
 
 #[derive(Default)]
-pub struct AdjustedBufferFontSize(Pixels);
+pub(crate) struct AdjustedBufferFontSize(Pixels);
 
 #[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
 pub struct ThemeSettingsContent {

crates/theme/src/styles/colors.rs

@@ -7,6 +7,7 @@ use crate::{PlayerColors, StatusColors, StatusColorsRefinement, SyntaxTheme, Sys
 #[derive(Refineable, Clone, Debug)]
 #[refineable(Debug, serde::Deserialize)]
 pub struct ThemeColors {
+    /// Border color. Used for most borders, is usually a high contrast color.
     pub border: Hsla,
     /// Border color. Used for deemphasized borders, like a visual divider between two sections
     pub border_variant: Hsla,

crates/theme/src/theme.rs

@@ -1,3 +1,11 @@
+//! # Theme
+//!
+//! This crate provides the theme system for Zed.
+//!
+//! ## Overview
+//!
+//! A theme is a collection of colors used to build a consistent appearance for UI components across the application.
+
 mod default_colors;
 mod default_theme;
 mod one_themes;

crates/theme/theme.md

@@ -0,0 +1,15 @@
+ # Theme
+
+ This crate provides the theme system for Zed.
+
+ ## Overview
+
+ A theme is a collection of colors used to build a consistent appearance for UI components across the application.
+ To produce a theme in Zed,
+
+ A theme is made of of two parts: A [ThemeFamily] and one or more [Theme]s.
+
+//
+ A [ThemeFamily] contains metadata like theme name, author, and theme-specific [ColorScales] as well as a series of themes.
+
+ - [ThemeColors] - A set of colors that are used to style the UI. Refer to the [ThemeColors] documentation for more information.