From e0458531ddb12a5385a3ef3b90a97d8264b82183 Mon Sep 17 00:00:00 2001
From: temportalflux <dustin.yost.t@gmail.com>
Date: Thu, 25 Jun 2026 14:56:33 -0400
Subject: [PATCH] add editable text documentation

---
 crates/gpui_elements/src/editable_text/actions.rs |  2 ++
 crates/gpui_elements/src/editable_text/caret.rs   | 10 +++++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/crates/gpui_elements/src/editable_text/actions.rs b/crates/gpui_elements/src/editable_text/actions.rs
index 9eac985501..251e23b400 100644
--- a/crates/gpui_elements/src/editable_text/actions.rs
+++ b/crates/gpui_elements/src/editable_text/actions.rs
@@ -143,6 +143,7 @@ pub fn default_bindings() -> gpui::ActionBindingCollection {
     bindings
 }
 
+/// Declares stubs for all editable-text actions that an element's state entity can implement.
 pub trait EditableTextActionHandler<Context>: Sized {
     fn escape(&mut self, _: &Escape, _w: &mut Window, _cx: &mut Context) {}
 
@@ -213,6 +214,7 @@ pub trait EditableTextActionHandler<Context>: Sized {
     }
 }
 
+/// Generic trait to support an element backed by an internal state entity to bind to all editable-text input actions.
 pub(super) trait EditableTextActionElement<State> {
     fn state_entity_rc(&self) -> &Rc<RefCell<WeakEntity<State>>>;
 
diff --git a/crates/gpui_elements/src/editable_text/caret.rs b/crates/gpui_elements/src/editable_text/caret.rs
index 4f0db28fd0..d7a5044d36 100644
--- a/crates/gpui_elements/src/editable_text/caret.rs
+++ b/crates/gpui_elements/src/editable_text/caret.rs
@@ -6,10 +6,14 @@ use smallvec::SmallVec;
 /// Default interval for caret blinking.
 pub const DEFAULT_BLINK_INTERVAL: Duration = Duration::from_millis(500);
 
+/// Events emitted that the [`Caret`] listens to.
 pub enum CaretNotify {
+    /// The caret should pause blinking in response to a user-action
     PauseBlinking,
 }
 
+/// State of an EditableText caret cursor, which supports features like blinking.
+/// Blinking is disabled by default.
 pub struct Caret {
     /// The frequency at which the caret blinks
     interval: Duration,
@@ -40,16 +44,20 @@ impl Default for Caret {
 }
 
 impl Caret {
+    /// Sets the blinking interval of the caret to the global "default".
+    /// The true default of the caret is "do not blink".
     pub fn blink_interval_default(mut self) -> Self {
         self.interval = DEFAULT_BLINK_INTERVAL;
         self
     }
 
+    /// Sets the blinking interval of the caret.
     pub fn blink_interval(mut self, interval: Duration) -> Self {
         self.interval = interval;
         self
     }
 
+    /// Listens for CaretNotify events on an entity (e.g. [`EditableTextState`]).
     pub fn subscribe_to<E>(&mut self, emitter: &Entity<E>, cx: &mut Context<Self>)
     where
         E: EventEmitter<CaretNotify>,
@@ -66,7 +74,7 @@ impl Caret {
     }
 
     /// Processes updates during prepaint and returns whether the caret is currently visible.
-    pub fn update_focus(&mut self, is_focused: bool, cx: &mut Context<Self>) -> bool {
+    pub(super) fn update_focus(&mut self, is_focused: bool, cx: &mut Context<Self>) -> bool {
         let was_focused = self.was_focused;
         self.was_focused = is_focused;