Add some Theme and UI docs (#3979)

Documents a number of items in the `theme` and `ui` crates. Release Notes: - N/A
2024-01-09 15:00:21 -05:00
parent 5b1894a9b1 51988f63d5
commit 510234ca71
26 changed files with 332 additions and 37 deletions
@@ -1515,7 +1515,7 @@ dependencies = [
 "tonic",
 "tower",
 "tracing",
- "tracing-log 0.1.3",
+ "tracing-log",
 "tracing-subscriber",
 "unindent",
 "util",
@@ -6930,9 +6930,9 @@ dependencies = [

 [[package]]
 name = "sharded-slab"
-version = "0.1.7"
+version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
+checksum = "900fba806f70c630b0a382d0d825e17a0f19fcd059a2ade1ff237bcddf446b31"
 dependencies = [
 "lazy_static",
 ]
@@ -8316,17 +8316,6 @@ dependencies = [
 "tracing-core",
 ]

-[[package]]
-name = "tracing-log"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3"
-dependencies = [
- "log",
- "once_cell",
- "tracing-core",
-]
-
 [[package]]
 name = "tracing-serde"
 version = "0.1.3"
@@ -8339,9 +8328,9 @@ dependencies = [

 [[package]]
 name = "tracing-subscriber"
-version = "0.3.18"
+version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ad0f048c97dbd9faa9b7df56362b8ebcaa52adb06b498c050d2f4e32f90a7a8b"
+checksum = "30a651bc37f915e81f087d86e62a18eec5f79550c7faff886f7090b4ea757c77"
 dependencies = [
 "matchers",
 "nu-ansi-term",
@@ -8354,7 +8343,7 @@ dependencies = [
 "thread_local",
 "tracing",
 "tracing-core",
- "tracing-log 0.2.0",
+ "tracing-log",
 "tracing-serde",
 ]

@@ -2,7 +2,9 @@ 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);

@@ -37,6 +39,10 @@ impl ColorScaleStep {
    ];
 }

+/// 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 +235,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,
@@ -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 {
@@ -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,
@@ -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;
@@ -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.
@@ -1,6 +1,6 @@
 use gpui::{ClickEvent, WindowContext};

-/// A trait for elements that can be clicked.
+/// A trait for elements that can be clicked. Enables the use of the `on_click` method.
 pub trait Clickable {
    /// Sets the click handler that will fire whenever the element is clicked.
    fn on_click(self, handler: impl Fn(&ClickEvent, &mut WindowContext) + 'static) -> Self;
@@ -8,6 +8,16 @@ pub enum Shape {
    RoundedRectangle,
 }

+/// An element that renders a user avatar with customizable appearance options.
+///
+/// # Examples
+///
+/// ```
+/// Avatar::new("path/to/image.png")
+///     .shape(Shape::Circle)
+///     .grayscale(true)
+///     .border_color(cx.theme().colors().border)
+/// ```
 #[derive(IntoElement)]
 pub struct Avatar {
    image: Img,
@@ -66,6 +76,16 @@ impl Avatar {
        }
    }

+    /// Sets the shape of the avatar image.
+    ///
+    /// This method allows the shape of the avatar to be specified using the [Shape] enum.
+    /// It modifies the corner radius of the image to match the specified shape.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// Avatar::new("path/to/image.png").shape(Shape::Circle);
+    /// ```
    pub fn shape(mut self, shape: Shape) -> Self {
        self.image = match shape {
            Shape::Circle => self.image.rounded_full(),
@@ -74,6 +94,13 @@ impl Avatar {
        self
    }

+    /// Applies a grayscale filter to the avatar image.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let avatar = Avatar::new("path/to/image.png").grayscale(true);
+    /// ```
    pub fn grayscale(mut self, grayscale: bool) -> Self {
        self.image = self.image.grayscale(grayscale);
        self
@@ -7,6 +7,64 @@ use crate::{

 use super::button_icon::ButtonIcon;

+/// An element that creates a button with a label and an optional icon.
+///
+/// Common buttons:
+/// - Label, Icon + Label: [Button] (this component)
+/// - Icon only: [IconButton]
+/// - Custom: [ButtonLike]
+///
+/// To create a more complex button than what the [Button] or [IconButton] components provide, use
+/// [ButtonLike] directly.
+///
+/// # Examples
+///
+/// **A button with a label**, is typically used in scenarios such as a form, where the button's label
+/// indicates what action will be performed when the button is clicked.
+///
+/// ```
+/// Button::new("button_id", "Click me!")
+///     .on_click(|event, cx| {
+///         // Handle click event
+///     });
+/// ```
+///
+/// **A toggleable button**, is typically used in scenarios such as a toolbar,
+/// where the button's state indicates whether a feature is enabled or not, or
+/// a trigger for a popover menu, where clicking the button toggles the visibility of the menu.
+///
+/// ```
+/// Button::new("button_id", "Click me!")
+///     .icon(IconName::Check)
+///     .selected(some_bool)
+///     .on_click(|event, cx| {
+///         // Handle click event
+///     });
+/// ```
+///
+/// To change the style of the button when it is selected use the [selected_style][Button::selected_style] method.
+///
+/// ```
+/// Button::new("button_id", "Click me!")
+///     .selected(some_bool)
+///     .selected_style(ButtonStyle::Tinted(TintColor::Accent))
+///     .on_click(|event, cx| {
+///         // Handle click event
+///     });
+/// ```
+/// This will create a button with a blue tinted background when selected.
+///
+/// **A full-width button**, is typically used in scenarios such as the bottom of a modal or form, where it occupies the entire width of its container.
+/// The button's content, including text and icons, is centered by default.
+///
+/// ```
+/// let button = Button::new("button_id", "Click me!")
+///     .full_width()
+///     .on_click(|event, cx| {
+///         // Handle click event
+///     });
+/// ```
+///
 #[derive(IntoElement)]
 pub struct Button {
    base: ButtonLike,
@@ -23,6 +81,12 @@ pub struct Button {
 }

 impl Button {
+    /// Creates a new [Button] with a specified identifier and label.
+    ///
+    /// This is the primary constructor for a `Button` component. It initializes
+    /// the button with the provided identifier and label text, setting all other
+    /// properties to their default values, which can be customized using the
+    /// builder pattern methods provided by this struct.
    pub fn new(id: impl Into<ElementId>, label: impl Into<SharedString>) -> Self {
        Self {
            base: ButtonLike::new(id),
@@ -39,46 +103,55 @@ impl Button {
        }
    }

+    /// Sets the color of the button's label.
    pub fn color(mut self, label_color: impl Into<Option<Color>>) -> Self {
        self.label_color = label_color.into();
        self
    }

+    /// Defines the size of the button's label.
    pub fn label_size(mut self, label_size: impl Into<Option<LabelSize>>) -> Self {
        self.label_size = label_size.into();
        self
    }

+    /// Sets the label used when the button is in a selected state.
    pub fn selected_label<L: Into<SharedString>>(mut self, label: impl Into<Option<L>>) -> Self {
        self.selected_label = label.into().map(Into::into);
        self
    }

+    /// Assigns an icon to the button.
    pub fn icon(mut self, icon: impl Into<Option<IconName>>) -> Self {
        self.icon = icon.into();
        self
    }

+    /// Sets the position of the icon relative to the label.
    pub fn icon_position(mut self, icon_position: impl Into<Option<IconPosition>>) -> Self {
        self.icon_position = icon_position.into();
        self
    }

+    /// Specifies the size of the button's icon.
    pub fn icon_size(mut self, icon_size: impl Into<Option<IconSize>>) -> Self {
        self.icon_size = icon_size.into();
        self
    }

+    /// Sets the color of the button's icon.
    pub fn icon_color(mut self, icon_color: impl Into<Option<Color>>) -> Self {
        self.icon_color = icon_color.into();
        self
    }

+    /// Chooses an icon to display when the button is in a selected state.
    pub fn selected_icon(mut self, icon: impl Into<Option<IconName>>) -> Self {
        self.selected_icon = icon.into();
        self
    }

+    /// Binds a key combination to the button for keyboard shortcuts.
    pub fn key_binding(mut self, key_binding: impl Into<Option<KeyBinding>>) -> Self {
        self.key_binding = key_binding.into();
        self
@@ -86,6 +159,22 @@ impl Button {
 }

 impl Selectable for Button {
+    /// Sets the selected state of the button.
+    ///
+    /// This method allows the selection state of the button to be specified.
+    /// It modifies the button's appearance to reflect its selected state.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// Button::new("button_id", "Click me!")
+    ///     .selected(true)
+    ///     .on_click(|event, cx| {
+    ///         // Handle click event
+    ///     });
+    /// ```
+    ///
+    /// Use [selected_style](Button::selected_style) to change the style of the button when it is selected.
    fn selected(mut self, selected: bool) -> Self {
        self.base = self.base.selected(selected);
        self
@@ -93,6 +182,19 @@ impl Selectable for Button {
 }

 impl SelectableButton for Button {
+    /// Sets the style for the button when selected.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// Button::new("button_id", "Click me!")
+    ///     .selected(true)
+    ///     .selected_style(ButtonStyle::Tinted(TintColor::Accent))
+    ///     .on_click(|event, cx| {
+    ///         // Handle click event
+    ///     });
+    /// ```
+    /// This results in a button with a blue tinted background when selected.
    fn selected_style(mut self, style: ButtonStyle) -> Self {
        self.base = self.base.selected_style(style);
        self
@@ -100,6 +202,22 @@ impl SelectableButton for Button {
 }

 impl Disableable for Button {
+    /// Disables the button.
+    ///
+    /// This method allows the button to be disabled. When a button is disabled,
+    /// it doesn't react to user interactions and its appearance is updated to reflect this.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// Button::new("button_id", "Click me!")
+    ///     .disabled(true)
+    ///     .on_click(|event, cx| {
+    ///         // Handle click event
+    ///     });
+    /// ```
+    ///
+    /// This results in a button that is disabled and does not respond to click events.
    fn disabled(mut self, disabled: bool) -> Self {
        self.base = self.base.disabled(disabled);
        self
@@ -107,6 +225,7 @@ impl Disableable for Button {
 }

 impl Clickable for Button {
+    /// Sets the click event handler for the button.
    fn on_click(
        mut self,
        handler: impl Fn(&gpui::ClickEvent, &mut WindowContext) + 'static,
@@ -117,11 +236,40 @@ impl Clickable for Button {
 }

 impl FixedWidth for Button {
+    /// Sets a fixed width for the button.
+    ///
+    /// This function allows a button to have a fixed width instead of automatically growing or shrinking.
+    /// Sets a fixed width for the button.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// Button::new("button_id", "Click me!")
+    ///     .width(DefiniteLength::Pixels(100))
+    ///     .on_click(|event, cx| {
+    ///         // Handle click event
+    ///     });
+    /// ```
+    ///
+    /// This sets the button's width to be exactly 100 pixels.
    fn width(mut self, width: DefiniteLength) -> Self {
        self.base = self.base.width(width);
        self
    }

+    /// Sets the button to occupy the full width of its container.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// Button::new("button_id", "Click me!")
+    ///     .full_width()
+    ///     .on_click(|event, cx| {
+    ///         // Handle click event
+    ///     });
+    /// ```
+    ///
+    /// This stretches the button to the full width of its container.
    fn full_width(mut self) -> Self {
        self.base = self.base.full_width();
        self
@@ -129,20 +277,42 @@ impl FixedWidth for Button {
 }

 impl ButtonCommon for Button {
+    /// Sets the button's id.
    fn id(&self) -> &ElementId {
        self.base.id()
    }

+    /// Sets the visual style of the button using a [ButtonStyle].
    fn style(mut self, style: ButtonStyle) -> Self {
        self.base = self.base.style(style);
        self
    }

+    /// Sets the button's size using a [ButtonSize].
    fn size(mut self, size: ButtonSize) -> Self {
        self.base = self.base.size(size);
        self
    }

+    /// Sets a tooltip for the button.
+    ///
+    /// This method allows a tooltip to be set for the button. The tooltip is a function that
+    /// takes a mutable reference to a [WindowContext] and returns an [AnyView]. The tooltip
+    /// is displayed when the user hovers over the button.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// Button::new("button_id", "Click me!")
+    ///     .tooltip(|cx| {
+    ///         Text::new("This is a tooltip").into()
+    ///     })
+    ///     .on_click(|event, cx| {
+    ///         // Handle click event
+    ///     });
+    /// ```
+    ///
+    /// This will create a button with a tooltip that displays "This is a tooltip" when hovered over.
    fn tooltip(mut self, tooltip: impl Fn(&mut WindowContext) -> AnyView + 'static) -> Self {
        self.base = self.base.tooltip(tooltip);
        self
@@ -4,10 +4,12 @@ use smallvec::SmallVec;

 use crate::prelude::*;

+/// A trait for buttons that can be Selected. Enables setting the [ButtonStyle] of a button when it is selected.
 pub trait SelectableButton: Selectable {
    fn selected_style(self, style: ButtonStyle) -> Self;
 }

+/// A common set of traits all buttons must implement.
 pub trait ButtonCommon: Clickable + Disableable {
    /// A unique element ID to identify the button.
    fn id(&self) -> &ElementId;
@@ -93,6 +95,7 @@ impl From<ButtonStyle> for Color {
    }
 }

+/// Sets the visual appearance of a button.
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy, Default)]
 pub enum ButtonStyle {
    /// A filled button with a solid background color. Provides emphasis versus
@@ -260,8 +263,7 @@ impl ButtonStyle {
    }
 }

-/// ButtonSize can also be used to help build  non-button elements
-/// that are consistently sized with buttons.
+/// Sets the height of a button. Can also be used to size  non-button elements to align with [Button]s.
 #[derive(Default, PartialEq, Clone, Copy)]
 pub enum ButtonSize {
    Large,
@@ -7,6 +7,7 @@ enum DividerDirection {
    Vertical,
 }

+/// Sets the color of a [Divider].
 #[derive(Default)]
 pub enum DividerColor {
    Border,
@@ -2,6 +2,28 @@ use gpui::WindowContext;

 use crate::{prelude::*, LabelCommon, LabelLike, LabelSize, LineHeightStyle};

+/// A struct representing a label element in the UI.
+///
+/// The `Label` struct stores the label text and common properties for a label element.
+/// It provides methods for modifying these properties.
+///
+/// # Examples
+///
+/// ```
+/// Label::new("Hello, World!")
+/// ```
+///
+/// **A colored label**, for example labeling a dangerous action:
+///
+/// ```
+/// let my_label = Label::new("Delete").color(Color::Error);
+/// ```
+///
+/// **A label with a strikethrough**, for example labeling something that has been deleted:
+///
+/// ```
+/// let my_label = Label::new("Deleted").strikethrough(true);
+/// ```
 #[derive(IntoElement)]
 pub struct Label {
    base: LabelLike,
@@ -9,6 +31,13 @@ pub struct Label {
 }

 impl Label {
+    /// Create a new `Label` with the given text.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let my_label = Label::new("Hello, World!");
+    /// ```
    pub fn new(label: impl Into<SharedString>) -> Self {
        Self {
            base: LabelLike::new(),
@@ -18,21 +47,49 @@ impl Label {
 }

 impl LabelCommon for Label {
+    /// Sets the size of the label using a [LabelSize].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let my_label = Label::new("Hello, World!").size(LabelSize::Large);
+    /// ```
    fn size(mut self, size: LabelSize) -> Self {
        self.base = self.base.size(size);
        self
    }

+    /// Sets the line height style of the label using a [LineHeightStyle].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let my_label = Label::new("Hello, World!").line_height_style(LineHeightStyle::Normal);
+    /// ```
    fn line_height_style(mut self, line_height_style: LineHeightStyle) -> Self {
        self.base = self.base.line_height_style(line_height_style);
        self
    }

+    /// Sets the color of the label using a [Color].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let my_label = Label::new("Hello, World!").color(Color::Primary);
+    /// ```
    fn color(mut self, color: Color) -> Self {
        self.base = self.base.color(color);
        self
    }

+    /// Sets the strikethrough property of the label.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let my_label = Label::new("Hello, World!").strikethrough(true);
+    /// ```
    fn strikethrough(mut self, strikethrough: bool) -> Self {
        self.base = self.base.strikethrough(strikethrough);
        self
@@ -19,6 +19,7 @@ pub enum LineHeightStyle {
    UiLabel,
 }

+/// A common set of traits all labels must implement.
 pub trait LabelCommon {
    fn size(self, size: LabelSize) -> Self;
    fn line_height_style(self, line_height_style: LineHeightStyle) -> Self;
@@ -108,6 +108,7 @@ impl<M: ManagedView> PopoverMenu<M> {
    }
 }

+/// Creates a [PopoverMenu]
 pub fn popover_menu<M: ManagedView>(id: impl Into<ElementId>) -> PopoverMenu<M> {
    PopoverMenu {
        id: id.into(),
@@ -39,6 +39,7 @@ impl<M: ManagedView> RightClickMenu<M> {
    }
 }

+/// Creates a [RightClickMenu]
 pub fn right_click_menu<M: ManagedView>(id: impl Into<ElementId>) -> RightClickMenu<M> {
    RightClickMenu {
        id: id.into(),
@@ -2,17 +2,13 @@ use gpui::{div, Div};

 use crate::StyledExt;

-/// Horizontally stacks elements.
-///
-/// Sets `flex()`, `flex_row()`, `items_center()`
+/// Horizontally stacks elements. Sets `flex()`, `flex_row()`, `items_center()`
 #[track_caller]
 pub fn h_stack() -> Div {
    div().h_flex()
 }

-/// Vertically stacks elements.
-///
-/// Sets `flex()`, `flex_col()`
+/// Vertically stacks elements. Sets `flex()`, `flex_col()`
 #[track_caller]
 pub fn v_stack() -> Div {
    div().v_flex()
@@ -1,4 +1,4 @@
-/// A trait for elements that can be disabled.
+/// A trait for elements that can be disabled. Generally used to implement disabling an element's interactivity and changing it's appearance to reflect that it is disabled.
 pub trait Disableable {
    /// Sets whether the element is disabled.
    fn disabled(self, disabled: bool) -> Self;
@@ -1,6 +1,6 @@
 use gpui::DefiniteLength;

-/// A trait for elements that have a fixed with.
+/// A trait for elements that can have a fixed with. Enables the use of the `width` and `full_width` methods.
 pub trait FixedWidth {
    /// Sets the width of the element.
    fn width(self, width: DefiniteLength) -> Self;
@@ -1,3 +1,5 @@
+//! The prelude of this crate. When building UI in zed you almost always want to import this.
+
 pub use gpui::prelude::*;
 pub use gpui::{
    div, px, relative, rems, AbsoluteLength, DefiniteLength, Div, Element, ElementId,
@@ -1,18 +1,25 @@
-/// A trait for elements that can be selected.
+/// A trait for elements that can be selected. Generally used to enable "toggle" or "active" behavior and styles on an element through the [Selection] status.
 pub trait Selectable {
    /// Sets whether the element is selected.
    fn selected(self, selected: bool) -> Self;
 }

+/// Represents the selection status of an element.
 #[derive(Debug, Default, PartialEq, Eq, Hash, Clone, Copy)]
 pub enum Selection {
+    /// The element is not selected.
    #[default]
    Unselected,
+    /// The selection state of the element is indeterminate.
    Indeterminate,
+    /// The element is selected.
    Selected,
 }

 impl Selection {
+    /// Returns the inverse of the current selection status.
+    ///
+    /// Indeterminate states become selected if inverted.
    pub fn inverse(&self) -> Self {
        match self {
            Self::Unselected | Self::Indeterminate => Self::Selected,
@@ -14,7 +14,7 @@ fn elevated<E: Styled>(this: E, cx: &mut WindowContext, index: ElevationIndex) -
        .shadow(index.shadow())
 }

-/// Extends [`Styled`](gpui::Styled) with Zed specific styling methods.
+/// Extends [gpui::Styled] with Zed specific styling methods.
 pub trait StyledExt: Styled + Sized {
    /// Horizontally stacks elements.
    ///
@@ -30,6 +30,7 @@ pub trait StyledExt: Styled + Sized {
        self.flex().flex_col()
    }

+    /// Sets the text size using a [UiTextSize].
    fn text_ui_size(self, size: UiTextSize) -> Self {
        self.text_size(size.rems())
    }
@@ -40,7 +41,7 @@ pub trait StyledExt: Styled + Sized {
    ///
    /// Note: The absolute size of this text will change based on a user's `ui_scale` setting.
    ///
-    /// Use [`text_ui_sm`] for regular-sized text.
+    /// Use `text_ui_sm` for smaller text.
    fn text_ui(self) -> Self {
        self.text_size(UiTextSize::default().rems())
    }
@@ -51,7 +52,7 @@ pub trait StyledExt: Styled + Sized {
    ///
    /// Note: The absolute size of this text will change based on a user's `ui_scale` setting.
    ///
-    /// Use [`text_ui`] for regular-sized text.
+    /// Use `text_ui` for regular-sized text.
    fn text_ui_sm(self) -> Self {
        self.text_size(UiTextSize::Small.rems())
    }
@@ -62,7 +63,7 @@ pub trait StyledExt: Styled + Sized {
    ///
    /// Note: The absolute size of this text will change based on a user's `ui_scale` setting.
    ///
-    /// Use [`text_ui`] for regular-sized text.
+    /// Use `text_ui` for regular-sized text.
    fn text_ui_xs(self) -> Self {
        self.text_size(UiTextSize::XSmall.rems())
    }
@@ -119,26 +120,32 @@ pub trait StyledExt: Styled + Sized {
        self.border_color(cx.theme().colors().border_variant)
    }

+    /// Sets the background color to red for debugging when building UI.
    fn debug_bg_red(self) -> Self {
        self.bg(hsla(0. / 360., 1., 0.5, 1.))
    }

+    /// Sets the background color to green for debugging when building UI.
    fn debug_bg_green(self) -> Self {
        self.bg(hsla(120. / 360., 1., 0.5, 1.))
    }

+    /// Sets the background color to blue for debugging when building UI.
    fn debug_bg_blue(self) -> Self {
        self.bg(hsla(240. / 360., 1., 0.5, 1.))
    }

+    /// Sets the background color to yellow for debugging when building UI.
    fn debug_bg_yellow(self) -> Self {
        self.bg(hsla(60. / 360., 1., 0.5, 1.))
    }

+    /// Sets the background color to cyan for debugging when building UI.
    fn debug_bg_cyan(self) -> Self {
        self.bg(hsla(160. / 360., 1., 0.5, 1.))
    }

+    /// Sets the background color to magenta for debugging when building UI.
    fn debug_bg_magenta(self) -> Self {
        self.bg(hsla(300. / 360., 1., 0.5, 1.))
    }
@@ -1,6 +1,7 @@
 use gpui::{Hsla, WindowContext};
 use theme::ActiveTheme;

+/// Sets a color that has a consistent meaning across all themes.
 #[derive(Debug, Default, PartialEq, Copy, Clone)]
 pub enum Color {
    #[default]
@@ -85,6 +85,7 @@ impl LayerIndex {
    }
 }

+/// Sets ann appropriate z-index for the given layer based on it's intended useage.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ElementIndex {
    Effect,
@@ -38,6 +38,7 @@ impl UiTextSize {
    }
 }

+/// Sets the size of a [Headline] element
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy, Default)]
 pub enum HeadlineSize {
    XSmall,
@@ -3,8 +3,6 @@
 //! This crate provides a set of UI primitives and components that are used to build all of the elements in Zed's UI.
 //!

-#![doc = include_str!("../docs/building-ui.md")]
-
 mod clickable;
 mod components;
 mod disableable;
@@ -1,3 +1,5 @@
+//! UI-related utilities (e.g. converting dates to a human-readable form).
+
 mod format_distance;

 pub use format_distance::*;