Document / lockdown more of GPUI

crates/gpui/src/gpui.rs

@@ -1,3 +1,33 @@
+//! # Welcome to GPUI!
+//!
+//! GPUI is a hybrid immedate and retained mode, GPU accelerated, UI framework
+//! for Rust, designed to support a wide variety of applications. GPUI is currently
+//! being actively developed and improved for the [Zed code editor](https://zed.dev/), and new versions
+//! will have breaking changes. You'll probably need to use the latest stable version
+//! of rust to use GPUI.
+//!
+//! # Getting started with GPUI
+//!
+//! TODO: Write a code sample showing how to create a window and render a simple
+//! div
+//!
+//! # Drawing interesting things
+//!
+//! TODO: Expand demo to show how to draw a more interesting scene, with
+//! a counter to store state and a button to increment it.
+//!
+//! # Interacting with your application state
+//!
+//! TODO: Expand demo to show GPUI entity interactions, like subscriptions and entities
+//! maybe make a network request to show async stuff?
+//!
+//! # Conclusion
+//!
+//! TODO: Wrap up with a conclusion and links to other places? Zed / GPUI website?
+//! Discord for chatting about it? Other tutorials or references?
+
+#![deny(missing_docs)]
+
 #[macro_use]
 mod action;
 mod app;
@@ -58,10 +88,10 @@ pub use elements::*;
 pub use executor::*;
 pub use geometry::*;
 pub use gpui_macros::{register_action, test, IntoElement, Render};
-pub use image_cache::*;
+use image_cache::*;
 pub use input::*;
 pub use interactive::*;
-pub use key_dispatch::*;
+use key_dispatch::*;
 pub use keymap::*;
 pub use platform::*;
 pub use refineable::*;
@@ -73,7 +103,7 @@ pub use smol::Timer;
 pub use style::*;
 pub use styled::*;
 pub use subscription::*;
-pub use svg_renderer::*;
+use svg_renderer::*;
 pub use taffy::{AvailableSpace, LayoutId};
 #[cfg(any(test, feature = "test-support"))]
 pub use test::*;
@@ -82,20 +112,23 @@ pub use util::arc_cow::ArcCow;
 pub use view::*;
 pub use window::*;
 
-use std::{
-    any::{Any, TypeId},
-    borrow::BorrowMut,
-};
+use std::{any::Any, borrow::BorrowMut};
 use taffy::TaffyLayoutEngine;
 
+/// The context trait, allows the different contexts in GPUI to be used
+/// interchangeably for certain operations.
 pub trait Context {
+    /// The result type for this context, used for async contexts that
+    /// can't hold a direct reference to the application context.
     type Result<T>;
 
+    /// Create a new model in the app context.
     fn new_model<T: 'static>(
         &mut self,
         build_model: impl FnOnce(&mut ModelContext<'_, T>) -> T,
     ) -> Self::Result<Model<T>>;
 
+    /// Update a model in the app context.
     fn update_model<T, R>(
         &mut self,
         handle: &Model<T>,
@@ -104,6 +137,7 @@ pub trait Context {
     where
         T: 'static;
 
+    /// Read a model from the app context.
     fn read_model<T, R>(
         &self,
         handle: &Model<T>,
@@ -112,10 +146,12 @@ pub trait Context {
     where
         T: 'static;
 
+    /// Update a window for the given handle.
     fn update_window<T, F>(&mut self, window: AnyWindowHandle, f: F) -> Result<T>
     where
         F: FnOnce(AnyView, &mut WindowContext<'_>) -> T;
 
+    /// Read a window off of the application context.
     fn read_window<T, R>(
         &self,
         window: &WindowHandle<T>,
@@ -125,7 +161,10 @@ pub trait Context {
         T: 'static;
 }
 
+/// This trait is used for the different visual contexts in GPUI that
+/// require a window to be present.
 pub trait VisualContext: Context {
+    /// Construct a new view in the window referenced by this context.
     fn new_view<V>(
         &mut self,
         build_view: impl FnOnce(&mut ViewContext<'_, V>) -> V,
@@ -133,12 +172,14 @@ pub trait VisualContext: Context {
     where
         V: 'static + Render;
 
+    /// Update a view with the given callback
     fn update_view<V: 'static, R>(
         &mut self,
         view: &View<V>,
         update: impl FnOnce(&mut V, &mut ViewContext<'_, V>) -> R,
     ) -> Self::Result<R>;
 
+    /// Replace the root view of a window with a new view.
     fn replace_root_view<V>(
         &mut self,
         build_view: impl FnOnce(&mut ViewContext<'_, V>) -> V,
@@ -146,38 +187,47 @@ pub trait VisualContext: Context {
     where
         V: 'static + Render;
 
+    /// Focus a view in the window, if it implements the [`FocusableView`] trait.
     fn focus_view<V>(&mut self, view: &View<V>) -> Self::Result<()>
     where
         V: FocusableView;
 
+    /// Dismiss a view in the window, if it implements the [`ManagedView`] trait.
     fn dismiss_view<V>(&mut self, view: &View<V>) -> Self::Result<()>
     where
         V: ManagedView;
 }
 
+/// A trait that allows models and views to be interchangeable in certain operations
 pub trait Entity<T>: Sealed {
+    /// The weak reference type for this entity.
     type Weak: 'static;
 
+    /// The ID for this entity
     fn entity_id(&self) -> EntityId;
+
+    /// Downgrade this entity to a weak reference.
     fn downgrade(&self) -> Self::Weak;
+
+    /// Upgrade this entity from a weak reference.
     fn upgrade_from(weak: &Self::Weak) -> Option<Self>
     where
         Self: Sized;
 }
 
+/// A trait for tying together the types of a GPUI entity and the events it can
+/// emit.
 pub trait EventEmitter<E: Any>: 'static {}
 
-pub enum GlobalKey {
-    Numeric(usize),
-    View(EntityId),
-    Type(TypeId),
-}
-
+/// A helper trait for auto-implementing certain methods on contexts that
+/// can be used interchangeably.
 pub trait BorrowAppContext {
+    /// Run a closure with a text style pushed onto the context.
     fn with_text_style<F, R>(&mut self, style: Option<TextStyleRefinement>, f: F) -> R
     where
         F: FnOnce(&mut Self) -> R;
 
+    /// Set a global value on the context.
     fn set_global<T: 'static>(&mut self, global: T);
 }
 
@@ -204,7 +254,9 @@ where
     }
 }
 
+/// A flatten equivalent for anyhow `Result`s.
 pub trait Flatten<T> {
+    /// Convert this type into a simple `Result<T>`.
     fn flatten(self) -> Result<T>;
 }