document app module in gpui 🎉

co-authored-by: Nathan <nathan@zed.dev>

crates/gpui/src/app.rs

@@ -1,3 +1,5 @@
+#![deny(missing_docs)]
+
 mod async_context;
 mod entity_map;
 mod model_context;
@@ -43,6 +45,9 @@ use util::{
     ResultExt,
 };
 
+/// The duration for which futures returned from [AppContext::on_app_context] or [ModelContext::on_app_quit] can run before the application fully quits.
+pub const SHUTDOWN_TIMEOUT: Duration = Duration::from_millis(100);
+
 /// Temporary(?) wrapper around [`RefCell<AppContext>`] to help us debug any double borrows.
 /// Strongly consider removing after stabilization.
 #[doc(hidden)]
@@ -187,6 +192,9 @@ type QuitHandler = Box<dyn FnOnce(&mut AppContext) -> LocalBoxFuture<'static, ()
 type ReleaseListener = Box<dyn FnOnce(&mut dyn Any, &mut AppContext) + 'static>;
 type NewViewListener = Box<dyn FnMut(AnyView, &mut WindowContext) + 'static>;
 
+/// Contains the state of the full application, and passed as a reference to a variety of callbacks.
+/// Other contexts such as [ModelContext], [WindowContext], and [ViewContext] deref to this type, making it the most general context type.
+/// You need a reference to an `AppContext` to access the state of a [Model].
 pub struct AppContext {
     pub(crate) this: Weak<AppCell>,
     pub(crate) platform: Rc<dyn Platform>,
@@ -312,7 +320,7 @@ impl AppContext {
         let futures = futures::future::join_all(futures);
         if self
             .background_executor
-            .block_with_timeout(Duration::from_millis(100), futures)
+            .block_with_timeout(SHUTDOWN_TIMEOUT, futures)
             .is_err()
         {
             log::error!("timed out waiting on app_will_quit");
@@ -446,6 +454,7 @@ impl AppContext {
             .collect()
     }
 
+    /// Returns a handle to the window that is currently focused at the platform level, if one exists.
     pub fn active_window(&self) -> Option<AnyWindowHandle> {
         self.platform.active_window()
     }
@@ -474,14 +483,17 @@ impl AppContext {
         self.platform.activate(ignoring_other_apps);
     }
 
+    /// Hide the application at the platform level.
     pub fn hide(&self) {
         self.platform.hide();
     }
 
+    /// Hide other applications at the platform level.
     pub fn hide_other_apps(&self) {
         self.platform.hide_other_apps();
     }
 
+    /// Unhide other applications at the platform level.
     pub fn unhide_other_apps(&self) {
         self.platform.unhide_other_apps();
     }
@@ -521,18 +533,25 @@ impl AppContext {
         self.platform.open_url(url);
     }
 
+    /// Returns the full pathname of the current app bundle.
+    /// If the app is not being run from a bundle, returns an error.
     pub fn app_path(&self) -> Result<PathBuf> {
         self.platform.app_path()
     }
 
+    /// Returns the file URL of the executable with the specified name in the application bundle
     pub fn path_for_auxiliary_executable(&self, name: &str) -> Result<PathBuf> {
         self.platform.path_for_auxiliary_executable(name)
     }
 
+    /// Returns the maximum duration in which a second mouse click must occur for an event to be a double-click event.
     pub fn double_click_interval(&self) -> Duration {
         self.platform.double_click_interval()
     }
 
+    /// Displays a platform modal for selecting paths.
+    /// When one or more paths are selected, they'll be relayed asynchronously via the returned oneshot channel.
+    /// If cancelled, a `None` will be relayed instead.
     pub fn prompt_for_paths(
         &self,
         options: PathPromptOptions,
@@ -540,22 +559,30 @@ impl AppContext {
         self.platform.prompt_for_paths(options)
     }
 
+    /// Displays a platform modal for selecting a new path where a file can be saved.
+    /// The provided directory will be used to set the iniital location.
+    /// When a path is selected, it is relayed asynchronously via the returned oneshot channel.
+    /// If cancelled, a `None` will be relayed instead.
     pub fn prompt_for_new_path(&self, directory: &Path) -> oneshot::Receiver<Option<PathBuf>> {
         self.platform.prompt_for_new_path(directory)
     }
 
+    /// Reveals the specified path at the platform level, such as in Finder on macOS.
     pub fn reveal_path(&self, path: &Path) {
         self.platform.reveal_path(path)
     }
 
+    /// Returns whether the user has configured scrollbars to auto-hide at the platform level.
     pub fn should_auto_hide_scrollbars(&self) -> bool {
         self.platform.should_auto_hide_scrollbars()
     }
 
+    /// Restart the application.
     pub fn restart(&self) {
         self.platform.restart()
     }
 
+    /// Returns the local timezone at the platform level.
     pub fn local_timezone(&self) -> UtcOffset {
         self.platform.local_timezone()
     }
@@ -745,7 +772,7 @@ impl AppContext {
     }
 
     /// Spawns the future returned by the given function on the thread pool. The closure will be invoked
-    /// with AsyncAppContext, which allows the application state to be accessed across await points.
+    /// with [AsyncAppContext], which allows the application state to be accessed across await points.
     pub fn spawn<Fut, R>(&self, f: impl FnOnce(AsyncAppContext) -> Fut) -> Task<R>
     where
         Fut: Future<Output = R> + 'static,
@@ -896,6 +923,8 @@ impl AppContext {
         self.globals_by_type.insert(global_type, lease.global);
     }
 
+    /// Arrange for the given function to be invoked whenever a view of the specified type is created.
+    /// The function will be passed a mutable reference to the view along with an appropriate context.
     pub fn observe_new_views<V: 'static>(
         &mut self,
         on_new: impl 'static + Fn(&mut V, &mut ViewContext<V>),
@@ -915,6 +944,8 @@ impl AppContext {
         subscription
     }
 
+    /// Observe the release of a model or view. The callback is invoked after the model or view
+    /// has no more strong references but before it has been dropped.
     pub fn observe_release<E, T>(
         &mut self,
         handle: &E,
@@ -935,6 +966,9 @@ impl AppContext {
         subscription
     }
 
+    /// Register a callback to be invoked when a keystroke is received by the application
+    /// in any window. Note that this fires after all other action and event mechansims have resolved
+    /// and that this API will not be invoked if the event's propogation is stopped.
     pub fn observe_keystrokes(
         &mut self,
         f: impl FnMut(&KeystrokeEvent, &mut WindowContext) + 'static,
@@ -958,6 +992,7 @@ impl AppContext {
         self.pending_effects.push_back(Effect::Refresh);
     }
 
+    /// Clear all key bindings in the app.
     pub fn clear_key_bindings(&mut self) {
         self.keymap.lock().clear();
         self.pending_effects.push_back(Effect::Refresh);
@@ -992,6 +1027,7 @@ impl AppContext {
         self.propagate_event = true;
     }
 
+    /// Build an action from some arbitrary data, typically a keymap entry.
     pub fn build_action(
         &self,
         name: &str,
@@ -1000,10 +1036,16 @@ impl AppContext {
         self.actions.build_action(name, data)
     }
 
+    /// Get a list of all action names that have been registered.
+    /// in the application. Note that registration only allows for
+    /// actions to be built dynamically, and is unrelated to binding
+    /// actions in the element tree.
     pub fn all_action_names(&self) -> &[SharedString] {
         self.actions.all_action_names()
     }
 
+    /// Register a callback to be invoked when the application is about to quit.
+    /// It is not possible to cancel the quit event at this point.
     pub fn on_app_quit<Fut>(
         &mut self,
         mut on_quit: impl FnMut(&mut AppContext) -> Fut + 'static,
@@ -1039,6 +1081,8 @@ impl AppContext {
         }
     }
 
+    /// Checks if the given action is bound in the current context, as defined by the app's current focus,
+    /// the bindings in the element tree, and any global action listeners.
     pub fn is_action_available(&mut self, action: &dyn Action) -> bool {
         if let Some(window) = self.active_window() {
             if let Ok(window_action_available) =
@@ -1052,10 +1096,13 @@ impl AppContext {
             .contains_key(&action.as_any().type_id())
     }
 
+    /// Set the menu bar for this application. This will replace any existing menu bar.
     pub fn set_menus(&mut self, menus: Vec<Menu>) {
         self.platform.set_menus(menus, &self.keymap.lock());
     }
 
+    /// Dispatch an action to the currently active window or global action handler
+    /// See [action::Action] for more information on how actions work
     pub fn dispatch_action(&mut self, action: &dyn Action) {
         if let Some(active_window) = self.active_window() {
             active_window
@@ -1110,6 +1157,7 @@ impl AppContext {
         }
     }
 
+    /// Is there currently something being dragged?
     pub fn has_active_drag(&self) -> bool {
         self.active_drag.is_some()
     }
@@ -1262,8 +1310,14 @@ impl<G: 'static> DerefMut for GlobalLease<G> {
 /// Contains state associated with an active drag operation, started by dragging an element
 /// within the window or by dragging into the app from the underlying platform.
 pub struct AnyDrag {
+    /// The view used to render this drag
     pub view: AnyView,
+
+    /// The value of the dragged item, to be dropped
     pub value: Box<dyn Any>,
+
+    /// This is used to render the dragged item in the same place
+    /// on the original element that the drag was initiated
     pub cursor_offset: Point<Pixels>,
 }
 
@@ -1271,12 +1325,19 @@ pub struct AnyDrag {
 /// tooltip behavior on a custom element. Otherwise, use [Div::tooltip].
 #[derive(Clone)]
 pub struct AnyTooltip {
+    /// The view used to display the tooltip
     pub view: AnyView,
+
+    /// The offset from the cursor to use, relative to the parent view
     pub cursor_offset: Point<Pixels>,
 }
 
+/// A keystroke event, and potentially the associated action
 #[derive(Debug)]
 pub struct KeystrokeEvent {
+    /// The keystroke that occurred
     pub keystroke: Keystroke,
+
+    /// The action that was resolved for the keystroke, if any
     pub action: Option<Box<dyn Action>>,
 }

crates/gpui/src/app/async_context.rs

@@ -7,6 +7,9 @@ use anyhow::{anyhow, Context as _};
 use derive_more::{Deref, DerefMut};
 use std::{future::Future, rc::Weak};
 
+/// An async-friendly version of [AppContext] with a static lifetime so it can be held across `await` points in async code.
+/// You're provided with an instance when calling [AppContext::spawn], and you can also create one with [AppContext::to_async].
+/// Internally, this holds a weak reference to an `AppContext`, so its methods are fallible to protect against cases where the [AppContext] is dropped.
 #[derive(Clone)]
 pub struct AsyncAppContext {
     pub(crate) app: Weak<AppCell>,
@@ -139,6 +142,8 @@ impl AsyncAppContext {
         self.foreground_executor.spawn(f(self.clone()))
     }
 
+    /// Determine whether global state of the specified type has been assigned.
+    /// Returns an error if the `AppContext` has been dropped.
     pub fn has_global<G: 'static>(&self) -> Result<bool> {
         let app = self
             .app
@@ -148,6 +153,9 @@ impl AsyncAppContext {
         Ok(app.has_global::<G>())
     }
 
+    /// Reads the global state of the specified type, passing it to the given callback.
+    /// Panics if no global state of the specified type has been assigned.
+    /// Returns an error if the `AppContext` has been dropped.
     pub fn read_global<G: 'static, R>(&self, read: impl FnOnce(&G, &AppContext) -> R) -> Result<R> {
         let app = self
             .app
@@ -157,6 +165,9 @@ impl AsyncAppContext {
         Ok(read(app.global(), &app))
     }
 
+    /// Reads the global state of the specified type, passing it to the given callback.
+    /// Similar to [read_global], but returns an error instead of panicking if no state of the specified type has been assigned.
+    /// Returns an error if no state of the specified type has been assigned the `AppContext` has been dropped.
     pub fn try_read_global<G: 'static, R>(
         &self,
         read: impl FnOnce(&G, &AppContext) -> R,
@@ -166,6 +177,8 @@ impl AsyncAppContext {
         Some(read(app.try_global()?, &app))
     }
 
+    /// A convenience method for [AppContext::update_global]
+    /// for updating the global state of the specified type.
     pub fn update_global<G: 'static, R>(
         &mut self,
         update: impl FnOnce(&mut G, &mut AppContext) -> R,
@@ -179,6 +192,8 @@ impl AsyncAppContext {
     }
 }
 
+/// A cloneable, owned handle to the application context,
+/// composed with the window associated with the current task.
 #[derive(Clone, Deref, DerefMut)]
 pub struct AsyncWindowContext {
     #[deref]
@@ -188,14 +203,16 @@ pub struct AsyncWindowContext {
 }
 
 impl AsyncWindowContext {
-    pub fn window_handle(&self) -> AnyWindowHandle {
-        self.window
-    }
-
     pub(crate) fn new(app: AsyncAppContext, window: AnyWindowHandle) -> Self {
         Self { app, window }
     }
 
+    /// Get the handle of the window this context is associated with.
+    pub fn window_handle(&self) -> AnyWindowHandle {
+        self.window
+    }
+
+    /// A convenience method for [WindowContext::update()]
     pub fn update<R>(
         &mut self,
         update: impl FnOnce(AnyView, &mut WindowContext) -> R,
@@ -203,10 +220,12 @@ impl AsyncWindowContext {
         self.app.update_window(self.window, update)
     }
 
+    /// A convenience method for [WindowContext::on_next_frame()]
     pub fn on_next_frame(&mut self, f: impl FnOnce(&mut WindowContext) + 'static) {
         self.window.update(self, |_, cx| cx.on_next_frame(f)).ok();
     }
 
+    /// A convenience method for [AppContext::global()]
     pub fn read_global<G: 'static, R>(
         &mut self,
         read: impl FnOnce(&G, &WindowContext) -> R,
@@ -214,6 +233,8 @@ impl AsyncWindowContext {
         self.window.update(self, |_, cx| read(cx.global(), cx))
     }
 
+    /// A convenience method for [AppContext::update_global()]
+    /// for updating the global state of the specified type.
     pub fn update_global<G, R>(
         &mut self,
         update: impl FnOnce(&mut G, &mut WindowContext) -> R,
@@ -224,6 +245,8 @@ impl AsyncWindowContext {
         self.window.update(self, |_, cx| cx.update_global(update))
     }
 
+    /// Schedule a future to be executed on the main thread. This is used for collecting
+    /// the results of background tasks and updating the UI.
     pub fn spawn<Fut, R>(&self, f: impl FnOnce(AsyncWindowContext) -> Fut) -> Task<R>
     where
         Fut: Future<Output = R> + 'static,

crates/gpui/src/app/entity_map.rs

@@ -31,6 +31,7 @@ impl From<u64> for EntityId {
 }
 
 impl EntityId {
+    /// Converts this entity id to a [u64]
     pub fn as_u64(self) -> u64 {
         self.0.as_ffi()
     }
@@ -140,7 +141,7 @@ impl EntityMap {
     }
 }
 
-pub struct Lease<'a, T> {
+pub(crate) struct Lease<'a, T> {
     entity: Option<Box<dyn Any>>,
     pub model: &'a Model<T>,
     entity_type: PhantomData<T>,
@@ -169,8 +170,9 @@ impl<'a, T> Drop for Lease<'a, T> {
 }
 
 #[derive(Deref, DerefMut)]
-pub struct Slot<T>(Model<T>);
+pub(crate) struct Slot<T>(Model<T>);
 
+/// A dynamically typed reference to a model, which can be downcast into a `Model<T>`.
 pub struct AnyModel {
     pub(crate) entity_id: EntityId,
     pub(crate) entity_type: TypeId,
@@ -195,14 +197,17 @@ impl AnyModel {
         }
     }
 
+    /// Returns the id associated with this model.
     pub fn entity_id(&self) -> EntityId {
         self.entity_id
     }
 
+    /// Returns the [TypeId] associated with this model.
     pub fn entity_type(&self) -> TypeId {
         self.entity_type
     }
 
+    /// Converts this model handle into a weak variant, which does not prevent it from being released.
     pub fn downgrade(&self) -> AnyWeakModel {
         AnyWeakModel {
             entity_id: self.entity_id,
@@ -211,6 +216,8 @@ impl AnyModel {
         }
     }
 
+    /// Converts this model handle into a strongly-typed model handle of the given type.
+    /// If this model handle is not of the specified type, returns itself as an error variant.
     pub fn downcast<T: 'static>(self) -> Result<Model<T>, AnyModel> {
         if TypeId::of::<T>() == self.entity_type {
             Ok(Model {
@@ -307,6 +314,8 @@ impl std::fmt::Debug for AnyModel {
     }
 }
 
+/// A strong, well typed reference to a struct which is managed
+/// by GPUI
 #[derive(Deref, DerefMut)]
 pub struct Model<T> {
     #[deref]
@@ -368,10 +377,12 @@ impl<T: 'static> Model<T> {
         self.any_model
     }
 
+    /// Grab a reference to this entity from the context.
     pub fn read<'a>(&self, cx: &'a AppContext) -> &'a T {
         cx.entities.read(self)
     }
 
+    /// Read the entity referenced by this model with the given function.
     pub fn read_with<R, C: Context>(
         &self,
         cx: &C,
@@ -437,6 +448,7 @@ impl<T> PartialEq<WeakModel<T>> for Model<T> {
     }
 }
 
+/// A type erased, weak reference to a model.
 #[derive(Clone)]
 pub struct AnyWeakModel {
     pub(crate) entity_id: EntityId,
@@ -445,10 +457,12 @@ pub struct AnyWeakModel {
 }
 
 impl AnyWeakModel {
+    /// Get the entity ID associated with this weak reference.
     pub fn entity_id(&self) -> EntityId {
         self.entity_id
     }
 
+    /// Check if this weak handle can be upgraded, or if the model has already been dropped
     pub fn is_upgradable(&self) -> bool {
         let ref_count = self
             .entity_ref_counts
@@ -458,6 +472,7 @@ impl AnyWeakModel {
         ref_count > 0
     }
 
+    /// Upgrade this weak model reference to a strong reference.
     pub fn upgrade(&self) -> Option<AnyModel> {
         let ref_counts = &self.entity_ref_counts.upgrade()?;
         let ref_counts = ref_counts.read();
@@ -485,6 +500,7 @@ impl AnyWeakModel {
         })
     }
 
+    /// Assert that model referenced by this weak handle has been dropped.
     #[cfg(any(test, feature = "test-support"))]
     pub fn assert_dropped(&self) {
         self.entity_ref_counts
@@ -527,6 +543,7 @@ impl PartialEq for AnyWeakModel {
 
 impl Eq for AnyWeakModel {}
 
+/// A weak reference to a model of the given type.
 #[derive(Deref, DerefMut)]
 pub struct WeakModel<T> {
     #[deref]
@@ -617,12 +634,12 @@ lazy_static::lazy_static! {
 
 #[cfg(any(test, feature = "test-support"))]
 #[derive(Clone, Copy, Debug, Default, Hash, PartialEq, Eq)]
-pub struct HandleId {
+pub(crate) struct HandleId {
     id: u64, // id of the handle itself, not the pointed at object
 }
 
 #[cfg(any(test, feature = "test-support"))]
-pub struct LeakDetector {
+pub(crate) struct LeakDetector {
     next_handle_id: u64,
     entity_handles: HashMap<EntityId, HashMap<HandleId, Option<backtrace::Backtrace>>>,
 }

crates/gpui/src/app/model_context.rs

@@ -11,6 +11,7 @@ use std::{
     future::Future,
 };
 
+/// The app context, with specialized behavior for the given model.
 #[derive(Deref, DerefMut)]
 pub struct ModelContext<'a, T> {
     #[deref]
@@ -24,20 +25,24 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         Self { app, model_state }
     }
 
+    /// The entity id of the model backing this context.
     pub fn entity_id(&self) -> EntityId {
         self.model_state.entity_id
     }
 
+    /// Returns a handle to the model belonging to this context.
     pub fn handle(&self) -> Model<T> {
         self.weak_model()
             .upgrade()
             .expect("The entity must be alive if we have a model context")
     }
 
+    /// Returns a weak handle to the model belonging to this context.
     pub fn weak_model(&self) -> WeakModel<T> {
         self.model_state.clone()
     }
 
+    /// Arranges for the given function to be called whenever [ModelContext::notify] or [ViewContext::notify] is called with the given model or view.
     pub fn observe<W, E>(
         &mut self,
         entity: &E,
@@ -59,6 +64,7 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         })
     }
 
+    /// Subscribe to an event type from another model or view
     pub fn subscribe<T2, E, Evt>(
         &mut self,
         entity: &E,
@@ -81,6 +87,7 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         })
     }
 
+    /// Register a callback to be invoked when GPUI releases this model.
     pub fn on_release(
         &mut self,
         on_release: impl FnOnce(&mut T, &mut AppContext) + 'static,
@@ -99,6 +106,7 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         subscription
     }
 
+    /// Register a callback to be run on the release of another model or view
     pub fn observe_release<T2, E>(
         &mut self,
         entity: &E,
@@ -124,6 +132,7 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         subscription
     }
 
+    /// Register a callback to for updates to the given global
     pub fn observe_global<G: 'static>(
         &mut self,
         mut f: impl FnMut(&mut T, &mut ModelContext<'_, T>) + 'static,
@@ -140,6 +149,8 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         subscription
     }
 
+    /// Arrange for the given function to be invoked whenever the application is quit.
+    /// The future returned from this callback will be polled for up to [gpui::SHUTDOWN_TIMEOUT] until the app fully quits.
     pub fn on_app_quit<Fut>(
         &mut self,
         mut on_quit: impl FnMut(&mut T, &mut ModelContext<T>) -> Fut + 'static,
@@ -165,6 +176,7 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         subscription
     }
 
+    /// Tell GPUI that this model has changed and observers of it should be notified.
     pub fn notify(&mut self) {
         if self
             .app
@@ -177,6 +189,7 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         }
     }
 
+    /// Update the given global
     pub fn update_global<G, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R
     where
         G: 'static,
@@ -187,6 +200,9 @@ impl<'a, T: 'static> ModelContext<'a, T> {
         result
     }
 
+    /// Spawn the future returned by the given function.
+    /// The function is provided a weak handle to the model owned by this context and a context that can be held across await points.
+    /// The returned task must be held or detached.
     pub fn spawn<Fut, R>(&self, f: impl FnOnce(WeakModel<T>, AsyncAppContext) -> Fut) -> Task<R>
     where
         T: 'static,
@@ -199,6 +215,7 @@ impl<'a, T: 'static> ModelContext<'a, T> {
 }
 
 impl<'a, T> ModelContext<'a, T> {
+    /// Emit an event of the specified type, which can be handled by other entities that have subscribed via `subscribe` methods on their respective contexts.
     pub fn emit<Evt>(&mut self, event: Evt)
     where
         T: EventEmitter<Evt>,