gpui: Clean up Styled doc comments (zed-industries#20731)

This PR cleans up the doc comments on the `Styled` trait to make them
more consistent.

Release Notes:

- N/A

crates/gpui/src/styled.rs

@@ -12,7 +12,7 @@ pub use gpui_macros::{
 use taffy::style::{AlignContent, Display};
 
 /// A trait for elements that can be styled.
-/// Use this to opt-in to a CSS-like styling API.
+/// Use this to opt-in to a utility CSS-like styling API.
 pub trait Styled: Sized {
     /// Returns a reference to the style memory of this element.
     fn style(&mut self) -> &mut StyleRefinement;
@@ -323,119 +323,128 @@ pub trait Styled: Sized {
         self
     }
 
-    /// Get the text style that has been configured on this element.
+    /// Returns a mutable reference to 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 its child elements.
+    /// Sets the text color of this element.
+    ///
+    /// This value cascades to its 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 its child elements.
+    /// Sets the font weight of this element
+    ///
+    /// This value cascades to its child elements.
     fn font_weight(mut self, weight: FontWeight) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
             .font_weight = Some(weight);
         self
     }
 
-    /// Set the background color of this element, this value cascades to its child elements.
+    /// Sets the background color of this element.
+    ///
+    /// This value cascades to its child elements.
     fn text_bg(mut self, bg: impl Into<Hsla>) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
             .background_color = Some(bg.into());
         self
     }
 
-    /// Set the text size of this element, this value cascades to its child elements.
+    /// Sets the text size of this element.
+    ///
+    /// This value cascades to its child elements.
     fn text_size(mut self, size: impl Into<AbsoluteLength>) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
             .font_size = Some(size.into());
         self
     }
 
-    /// Set the text size to 'extra small',
-    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
+    /// Sets the text size to 'extra small'.
+    /// [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)
             .font_size = Some(rems(0.75).into());
         self
     }
 
-    /// Set the text size to 'small',
-    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
+    /// Sets the text size to 'small'.
+    /// [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)
             .font_size = Some(rems(0.875).into());
         self
     }
 
-    /// Reset the text styling for this element and its children.
+    /// Sets the text size to 'base'.
+    /// [Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
     fn text_base(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
             .font_size = Some(rems(1.0).into());
         self
     }
 
-    /// Set the text size to 'large',
-    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
+    /// Sets the text size to 'large'.
+    /// [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)
             .font_size = Some(rems(1.125).into());
         self
     }
 
-    /// Set the text size to 'extra large',
-    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
+    /// Sets the text size to 'extra large'.
+    /// [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)
             .font_size = Some(rems(1.25).into());
         self
     }
 
-    /// Set the text size to 'extra-extra large',
-    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
+    /// Sets the text size to 'extra extra large'.
+    /// [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)
             .font_size = Some(rems(1.5).into());
         self
     }
 
-    /// Set the text size to 'extra-extra-extra large',
-    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
+    /// Sets the text size to 'extra extra extra large'.
+    /// [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)
             .font_size = Some(rems(1.875).into());
         self
     }
 
-    /// Set the font style to 'non-italic',
-    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-style#italicizing-text)
-    fn non_italic(mut self) -> Self {
+    /// Sets the font style of the element to italic.
+    /// [Docs](https://tailwindcss.com/docs/font-style#italicizing-text)
+    fn italic(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
-            .font_style = Some(FontStyle::Normal);
+            .font_style = Some(FontStyle::Italic);
         self
     }
 
-    /// Set the font style to 'italic',
-    /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-style#italicizing-text)
-    fn italic(mut self) -> Self {
+    /// Sets the font style of the element to normal (not italic).
+    /// [Docs](https://tailwindcss.com/docs/font-style#italicizing-text)
+    fn not_italic(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
-            .font_style = Some(FontStyle::Italic);
+            .font_style = Some(FontStyle::Normal);
         self
     }
 
@@ -450,87 +459,96 @@ pub trait Styled: Sized {
         self
     }
 
-    /// Remove the text decoration on this element, this value cascades to its child elements.
+    /// Removes the text decoration on this element.
+    ///
+    /// This value cascades to its child elements.
     fn text_decoration_none(mut self) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
             .underline = None;
         self
     }
 
-    /// Set the color for the underline on this element
+    /// Sets 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);
         underline.color = Some(color.into());
         self
     }
 
-    /// Set the underline to a solid line
+    /// Sets the text decoration style to a solid line.
+    /// [Docs](https://tailwindcss.com/docs/text-decoration-style)
     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);
         underline.wavy = false;
         self
     }
 
-    /// Set the underline to a wavy line
+    /// Sets the text decoration style to a wavy line.
+    /// [Docs](https://tailwindcss.com/docs/text-decoration-style)
     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);
         underline.wavy = true;
         self
     }
 
-    /// Set the underline to be 0 thickness, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
+    /// Sets the text decoration to be 0px thick.
+    /// [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);
         underline.thickness = px(0.);
         self
     }
 
-    /// Set the underline to be 1px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
+    /// Sets the text decoration to be 1px thick.
+    /// [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);
         underline.thickness = px(1.);
         self
     }
 
-    /// Set the underline to be 2px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
+    /// Sets the text decoration to be 2px thick.
+    /// [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);
         underline.thickness = px(2.);
         self
     }
 
-    /// Set the underline to be 4px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
+    /// Sets the text decoration to be 4px thick.
+    /// [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);
         underline.thickness = px(4.);
         self
     }
 
-    /// Set the underline to be 8px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
+    /// Sets the text decoration to be 8px thick.
+    /// [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);
         underline.thickness = px(8.);
         self
     }
 
-    /// Change the font family on this element and its children.
+    /// Sets the font family of this element and its children.
     fn font_family(mut self, family_name: impl Into<SharedString>) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
             .font_family = Some(family_name.into());
         self
     }
 
-    /// Change the font of this element and its children.
+    /// Sets the font of this element and its children.
     fn font(mut self, font: Font) -> Self {
         let Font {
             family,
@@ -550,28 +568,28 @@ pub trait Styled: Sized {
         self
     }
 
-    /// Set the line height on this element and its children.
+    /// Sets the line height of this element and its children.
     fn line_height(mut self, line_height: impl Into<DefiniteLength>) -> Self {
         self.text_style()
             .get_or_insert_with(Default::default)
             .line_height = Some(line_height.into());
         self
     }
 
-    /// Set opacity on this element and its children.
+    /// Sets the opacity of this element and its children.
     fn opacity(mut self, opacity: f32) -> Self {
         self.style().opacity = Some(opacity);
         self
     }
 
-    /// Draw a debug border around this element.
+    /// Draws 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.
+    /// Draws 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);