Document more styling functions

crates/gpui/src/style.rs

@@ -7,7 +7,7 @@ use crate::{
     SizeRefinement, Styled, TextRun,
 };
 use collections::HashSet;
-use refineable::{Cascade, Refineable};
+use refineable::Refineable;
 use smallvec::SmallVec;
 pub use taffy::style::{
     AlignContent, AlignItems, AlignSelf, Display, FlexDirection, FlexWrap, JustifyContent,
@@ -15,10 +15,12 @@ pub use taffy::style::{
 };
 
 #[cfg(debug_assertions)]
+/// Use this struct for interfacing with the 'debug_below' styling from your own elements.
+/// If a parent element has this style set on it, then this struct will be set as a global in
+/// GPUI.
 pub struct DebugBelow;
 
-pub type StyleCascade = Cascade<Style>;
+/// The CSS styling that can be applied to an element via the `Styled` trait
-
 #[derive(Clone, Refineable, Debug)]
 #[refineable(Debug)]
 pub struct Style {
@@ -104,16 +106,20 @@ pub struct Style {
     /// Box Shadow of the element
     pub box_shadow: SmallVec<[BoxShadow; 2]>,
 
-    /// TEXT
+    /// The text style of this element
     pub text: TextStyleRefinement,
 
     /// The mouse cursor style shown when the mouse pointer is over an element.
     pub mouse_cursor: Option<CursorStyle>,
 
+    /// The z-index to set for this element
     pub z_index: Option<u16>,
 
+    /// Whether to draw a red debugging outline around this element
     #[cfg(debug_assertions)]
     pub debug: bool,
+
+    /// Whether to draw a red debugging outline around this element and all of it's conforming children
     #[cfg(debug_assertions)]
     pub debug_below: bool,
 }
@@ -124,40 +130,71 @@ impl Styled for StyleRefinement {
     }
 }
 
+/// The value of the visibility property, similar to the CSS property `visibility`
 #[derive(Default, Clone, Copy, Debug, Eq, PartialEq)]
 pub enum Visibility {
+    /// The element should be drawn as normal.
     #[default]
     Visible,
+    /// The element should not be drawn, but should still take up space in the layout.
     Hidden,
 }
 
+/// The possible values of the box-shadow property
 #[derive(Clone, Debug)]
 pub struct BoxShadow {
+    /// What color should the shadow have?
     pub color: Hsla,
+    /// How should it be offset from it's element?
     pub offset: Point<Pixels>,
+    /// How much should the shadow be blurred?
     pub blur_radius: Pixels,
+    /// How much should the shadow spread?
     pub spread_radius: Pixels,
 }
 
+/// How to handle whitespace in text
 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
 pub enum WhiteSpace {
+    /// Normal line wrapping when text overflows the width of the element
     #[default]
     Normal,
+    /// No line wrapping, text will overflow the width of the element
     Nowrap,
 }
 
+/// The properties that can be used to style text in GPUI
 #[derive(Refineable, Clone, Debug, PartialEq)]
 #[refineable(Debug)]
 pub struct TextStyle {
+    /// The color of the text
     pub color: Hsla,
+
+    /// The font family to use
     pub font_family: SharedString,
+
+    /// The font features to use
     pub font_features: FontFeatures,
+
+    /// The font size to use, in pixels or rems.
     pub font_size: AbsoluteLength,
+
+    /// The line height to use, in pixels or fractions
     pub line_height: DefiniteLength,
+
+    /// The font weight, e.g. bold
     pub font_weight: FontWeight,
+
+    /// The font style, e.g. italic
     pub font_style: FontStyle,
+
+    /// The background color of the text
     pub background_color: Option<Hsla>,
+
+    /// The underline style of the text
     pub underline: Option<UnderlineStyle>,
+
+    /// How to handle whitespace in the text
     pub white_space: WhiteSpace,
 }
 
@@ -180,6 +217,7 @@ impl Default for TextStyle {
 }
 
 impl TextStyle {
+    /// Create a new text style with the given highlighting applied.
     pub fn highlight(mut self, style: impl Into<HighlightStyle>) -> Self {
         let style = style.into();
         if let Some(weight) = style.font_weight {
@@ -208,6 +246,7 @@ impl TextStyle {
         self
     }
 
+    /// Get the font configured for this text style.
     pub fn font(&self) -> Font {
         Font {
             family: self.font_family.clone(),
@@ -222,6 +261,7 @@ impl TextStyle {
         self.line_height.to_pixels(self.font_size, rem_size).round()
     }
 
+    /// Convert this text style into a [`TextRun`], for the given length of the text.
     pub fn to_run(&self, len: usize) -> TextRun {
         TextRun {
             len,
@@ -238,19 +278,33 @@ impl TextStyle {
     }
 }
 
+/// A highlight style to apply, similar to a `TextStyle` except
+/// for a single font, uniformly sized and spaced text.
 #[derive(Copy, Clone, Debug, Default, PartialEq)]
 pub struct HighlightStyle {
+    /// The color of the text
     pub color: Option<Hsla>,
+
+    /// The font weight, e.g. bold
     pub font_weight: Option<FontWeight>,
+
+    /// The font style, e.g. italic
     pub font_style: Option<FontStyle>,
+
+    /// The background color of the text
     pub background_color: Option<Hsla>,
+
+    /// The underline style of the text
     pub underline: Option<UnderlineStyle>,
+
+    /// Similar to the CSS `opacity` property, this will cause the text to be less vibrant.
     pub fade_out: Option<f32>,
 }
 
 impl Eq for HighlightStyle {}
 
 impl Style {
+    /// Get the text style in this element style.
     pub fn text_style(&self) -> Option<&TextStyleRefinement> {
         if self.text.is_some() {
             Some(&self.text)
@@ -259,6 +313,8 @@ impl Style {
         }
     }
 
+    /// Get the content mask for this element style, based on the given bounds.
+    /// If the element does not hide it's overflow, this will return `None`.
     pub fn overflow_mask(
         &self,
         bounds: Bounds<Pixels>,
@@ -480,20 +536,29 @@ impl Default for Style {
     }
 }
 
+/// The properties that can be applied to an underline.
 #[derive(Refineable, Copy, Clone, Default, Debug, PartialEq, Eq)]
 #[refineable(Debug)]
 pub struct UnderlineStyle {
+    /// The thickness of the underline.
     pub thickness: Pixels,
+
+    /// The color of the underline.
     pub color: Option<Hsla>,
+
+    /// Whether the underline should be wavy, like in a spell checker.
     pub wavy: bool,
 }
 
+/// The kinds of fill that can be applied to a shape.
 #[derive(Clone, Debug)]
 pub enum Fill {
+    /// A solid color fill.
     Color(Hsla),
 }
 
 impl Fill {
+    /// Unwrap this fill into a solid color, if it is one.
     pub fn color(&self) -> Option<Hsla> {
         match self {
             Fill::Color(color) => Some(*color),
@@ -539,6 +604,8 @@ impl From<&TextStyle> for HighlightStyle {
 }
 
 impl HighlightStyle {
+    /// Blend this highlight style with another.
+    /// Non-continuous properties, like font_weight and font_style, are overwritten.
     pub fn highlight(&mut self, other: HighlightStyle) {
         match (self.color, other.color) {
             (Some(self_color), Some(other_color)) => {
@@ -612,6 +679,7 @@ impl From<Rgba> for HighlightStyle {
     }
 }
 
+/// Combine and merge the highlights and ranges in the two iterators.
 pub fn combine_highlights(
     a: impl IntoIterator<Item = (Range<usize>, HighlightStyle)>,
     b: impl IntoIterator<Item = (Range<usize>, HighlightStyle)>,

crates/gpui/src/styled.rs

@@ -7,17 +7,21 @@ use crate::{BoxShadow, TextStyleRefinement};
 use smallvec::{smallvec, SmallVec};
 use taffy::style::{Display, Overflow};
 
+/// A trait for elements that can be styled.
+/// Use this to opt-in to a CSS-like styling API.
 pub trait Styled: Sized {
+    /// Returns a reference to the style memory of this element.
     fn style(&mut self) -> &mut StyleRefinement;
 
     gpui_macros::style_helpers!();
 
+    /// Set the z-index of this element.
     fn z_index(mut self, z_index: u16) -> Self {
         self.style().z_index = Some(z_index);
         self
     }
 
-    /// Sets the size of the element to the full width and height.
+    /// Sets the size of the element to sthe full width and height.
     fn full(mut self) -> Self {
         self.style().size.width = Some(relative(1.).into());
         self.style().size.height = Some(relative(1.).into());
@@ -88,6 +92,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the cursor style when hovering over this element
     fn cursor(mut self, cursor: CursorStyle) -> Self {
         self.style().mouse_cursor = Some(cursor);
         self
@@ -511,16 +516,19 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Get the text style that has been configured on this element.
     fn text_style(&mut self) -> &mut Option<TextStyleRefinement> {
         let style: &mut StyleRefinement = self.style();
         &mut style.text
     }
 
+    /// Set the text color of this element, this value cascades to it's child elements.
     fn text_color(mut self, color: impl Into<Hsla>) -> Self {
         self.text_style().get_or_insert_with(Default::default).color = Some(color.into());
         self
     }
 
+    /// Set the font weight of this element, this value cascades to it's child elements.
     fn font_weight(mut self, weight: FontWeight) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -528,6 +536,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the background color of this element, this value cascades to it's child elements.
     fn text_bg(mut self, bg: impl Into<Hsla>) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -535,6 +544,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the text size of this element, this value cascades to it's child elements.
     fn text_size(mut self, size: impl Into<AbsoluteLength>) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -542,6 +552,8 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the text size to 'extra small',
+    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
     fn text_xs(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -549,6 +561,8 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the text size to 'small',
+    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
     fn text_sm(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -556,6 +570,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Reset the text styling for this element and it's children.
     fn text_base(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -563,6 +578,8 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the text size to 'large',
+    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
     fn text_lg(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -570,6 +587,8 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the text size to 'extra large',
+    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
     fn text_xl(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -577,6 +596,8 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the text size to 'extra-extra large',
+    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
     fn text_2xl(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -584,6 +605,8 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the text size to 'extra-extra-extra large',
+    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
     fn text_3xl(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -591,6 +614,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Remove the text decoration on this element, this value cascades to it's child elements.
     fn text_decoration_none(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -598,6 +622,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the color for the underline on this element
     fn text_decoration_color(mut self, color: impl Into<Hsla>) -> Self {
         let style = self.text_style().get_or_insert_with(Default::default);
         let underline = style.underline.get_or_insert_with(Default::default);
@@ -605,6 +630,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the underline to a solid line
     fn text_decoration_solid(mut self) -> Self {
         let style = self.text_style().get_or_insert_with(Default::default);
         let underline = style.underline.get_or_insert_with(Default::default);
@@ -612,6 +638,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the underline to a wavy line
     fn text_decoration_wavy(mut self) -> Self {
         let style = self.text_style().get_or_insert_with(Default::default);
         let underline = style.underline.get_or_insert_with(Default::default);
@@ -619,6 +646,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the underline to be 0 thickness, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
     fn text_decoration_0(mut self) -> Self {
         let style = self.text_style().get_or_insert_with(Default::default);
         let underline = style.underline.get_or_insert_with(Default::default);
@@ -626,6 +654,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the underline to be 1px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
     fn text_decoration_1(mut self) -> Self {
         let style = self.text_style().get_or_insert_with(Default::default);
         let underline = style.underline.get_or_insert_with(Default::default);
@@ -633,6 +662,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the underline to be 2px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
     fn text_decoration_2(mut self) -> Self {
         let style = self.text_style().get_or_insert_with(Default::default);
         let underline = style.underline.get_or_insert_with(Default::default);
@@ -640,6 +670,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the underline to be 4px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
     fn text_decoration_4(mut self) -> Self {
         let style = self.text_style().get_or_insert_with(Default::default);
         let underline = style.underline.get_or_insert_with(Default::default);
@@ -647,6 +678,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the underline to be 8px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
     fn text_decoration_8(mut self) -> Self {
         let style = self.text_style().get_or_insert_with(Default::default);
         let underline = style.underline.get_or_insert_with(Default::default);
@@ -654,6 +686,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Change the font on this element and it's children.
     fn font(mut self, family_name: impl Into<SharedString>) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -661,6 +694,7 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Set the line height on this element and it's children.
     fn line_height(mut self, line_height: impl Into<DefiniteLength>) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
@@ -668,12 +702,14 @@ pub trait Styled: Sized {
         self
     }
 
+    /// Draw a debug border around this element.
     #[cfg(debug_assertions)]
     fn debug(mut self) -> Self {
         self.style().debug = Some(true);
         self
     }
 
+    /// Draw a debug border on all conforming elements below this element.
     #[cfg(debug_assertions)]
     fn debug_below(mut self) -> Self {
         self.style().debug_below = Some(true);

crates/gpui/src/text_system/font_features.rs

@@ -4,9 +4,9 @@ use schemars::{
 };
 
 macro_rules! create_definitions {
-    ($($(#[$meta:meta])* ($name:ident, $idx:expr), ($comment:tt)),* $(,)?) => {
+    ($($(#[$meta:meta])* ($name:ident, $idx:expr)),* $(,)?) => {
 
-        /// The font features that can be configured for a given font.
+        /// The OpenType features that can be configured for a given font.
         #[derive(Default, Copy, Clone, Eq, PartialEq, Hash)]
         pub struct FontFeatures {
             enabled: u64,
@@ -15,7 +15,7 @@ macro_rules! create_definitions {
 
         impl FontFeatures {
             $(
-                /// $comment
+                /// Get the current value of the corresponding OpenType feature
                 pub fn $name(&self) -> Option<bool> {
                     if (self.enabled & (1 << $idx)) != 0 {
                         Some(true)
@@ -128,7 +128,7 @@ macro_rules! create_definitions {
 }
 
 create_definitions!(
-    (calt, 0, CALT),
+    (calt, 0),
     (case, 1),
     (cpsp, 2),
     (frac, 3),