Document ui crate traits

Nate Butler created 2 years ago

Change summary

crates/ui/src/clickable.rs                     | 2 +-
crates/ui/src/components/button/button_like.rs | 2 ++
crates/ui/src/components/label/label_like.rs   | 1 +
crates/ui/src/disableable.rs                   | 2 +-
crates/ui/src/fixed.rs                         | 2 +-
crates/ui/src/selectable.rs                    | 9 ++++++++-
crates/ui/src/styled_ext.rs                    | 8 +++++++-
7 files changed, 21 insertions(+), 5 deletions(-)

Detailed changes

crates/ui/src/clickable.rs

@@ -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;

crates/ui/src/components/button/button_like.rs

@@ -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;

crates/ui/src/components/label/label_like.rs

@@ -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;

crates/ui/src/disableable.rs

@@ -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;

crates/ui/src/fixed.rs

@@ -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;

crates/ui/src/selectable.rs

@@ -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,

crates/ui/src/styled_ext.rs

@@ -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.
     ///
@@ -119,26 +119,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.))
     }