Add module documentation to GPUI and make gpui.rs example compile

crates/gpui/src/color.rs

@@ -3,11 +3,11 @@ use serde::de::{self, Deserialize, Deserializer, Visitor};
 use std::fmt;
 
 /// Convert an RGB hex color code number to a color type
-pub fn rgb<C: From<Rgba>>(hex: u32) -> C {
+pub fn rgb(hex: u32) -> Rgba {
     let r = ((hex >> 16) & 0xFF) as f32 / 255.0;
     let g = ((hex >> 8) & 0xFF) as f32 / 255.0;
     let b = (hex & 0xFF) as f32 / 255.0;
-    Rgba { r, g, b, a: 1.0 }.into()
+    Rgba { r, g, b, a: 1.0 }
 }
 
 /// Convert an RGBA hex color code number to [`Rgba`]
@@ -40,7 +40,6 @@ impl fmt::Debug for Rgba {
 
 impl Rgba {
     /// Create a new [`Rgba`] color by blending this and another color together
-    /// TODO!(docs): find the source for this algorithm
     pub fn blend(&self, other: Rgba) -> Self {
         if other.a >= 1.0 {
             other

crates/gpui/src/elements/div.rs

@@ -14,13 +14,6 @@
 //! as several associated traits. Together, these provide the full suite of Dom-like events
 //! and Tailwind-like styling that you can use to build your own custom elements. Div is
 //! constructed by combining these two systems into an all-in-one element.
-//!
-//! # Capturing and bubbling
-//!
-//! Note that while event dispatch in GPUI uses similar names and concepts to the web
-//! even API, the details are very different. See the documentation in [TODO!(docs)
-//! DOCUMENT EVENT DISPATCH SOMEWHERE IN WINDOW CONTEXT] for more details
-//!
 
 use crate::{
     point, px, size, Action, AnyDrag, AnyElement, AnyTooltip, AnyView, AppContext, Bounds,

crates/gpui/src/elements/text.rs

@@ -46,6 +46,18 @@ impl IntoElement for &'static str {
     }
 }
 
+impl IntoElement for String {
+    type Element = SharedString;
+
+    fn element_id(&self) -> Option<ElementId> {
+        None
+    }
+
+    fn into_element(self) -> Self::Element {
+        self.into()
+    }
+}
+
 impl Element for SharedString {
     type State = TextState;
 

crates/gpui/src/gpui.rs

@@ -1,30 +1,60 @@
 //! # Welcome to GPUI!
 //!
 //! GPUI is a hybrid immediate 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.
+//! for Rust, designed to support a wide variety of applications.
 //!
-//! # Getting started with GPUI
+//! ## Getting Started
 //!
-//! TODO!(docs): Write a code sample showing how to create a window and render a simple
-//! div
+//! GPUI is still in active development as we work on the Zed code editor and isn't yet on crates.io.
+//! You'll also need to use the latest version of stable rust. Add the following to your Cargo.toml:
 //!
-//! # Drawing interesting things
+//! gpui = { git = "https://github.com/zed-industries/zed" }
 //!
-//! TODO!(docs): Expand demo to show how to draw a more interesting scene, with
-//! a counter to store state and a button to increment it.
+//! Everything in GPUI starts with an [`App`]. You can create one with [`App::new`], and
+//! kick off your application by passing a callback to [`App::run`]. Inside this callback,
+//! you can create a new window with [`AppContext::open_window`], and register your first root
+//! view. See [gpui.rs](https://www.gpui.rs/) for a complete example.
 //!
-//! # Interacting with your application state
+//! ## The Big Picture
 //!
-//! TODO!(docs): Expand demo to show GPUI entity interactions, like subscriptions and entities
-//! maybe make a network request to show async stuff?
+//! GPUI offers three different [registers](https://en.wikipedia.org/wiki/Register_(sociolinguistics)) depending on your needs:
 //!
-//! # Conclusion
+//! - State management and communication with Models. Whenever you need to store application state
+//!   that communicates between different parts of your application, you'll want to use GPUI's
+//!   models. Models are owned by GPUI and are only accessible through an owned smart pointer
+//!   similar to an [`Rc`]. See the [`app::model_context`] module for more information.
 //!
-//! TODO!(docs): Wrap up with a conclusion and links to other places? Zed / GPUI website?
-//! Discord for chatting about it? Other tutorials or references?
+//! - High level, declarative UI with Views. All UI in GPUI starts with a View. A view is simply
+//!   a model that can be rendered, via the [`Render`] trait. At the start of each frame, GPUI
+//!   will call this render method on the root view of a given window. Views build a tree of
+//!   `elements`, lay them out and style them with a tailwind-style API, and then give them to
+//!   GPUI to turn into pixels. See the [`div`] element for an all purpose swiss-army knife of
+//!   rendering.
+//!
+//! - Low level, imperative UI with Elements. Elements are the building blocks of UI in GPUI, and they
+//!   provide a nice wrapper around an imperative API that provides as much flexibility and control as
+//!   you need. Elements have total control over how they and their child elements are rendered and and
+//!   can be used for making efficient views into large lists, implement custom layouting for a code editor,
+//!   and anything else you can think of. See the [`element`] module for more information.
+//!
+//!  Each of these registers has one or more corresponding contexts that can be accessed from all GPUI services.
+//!  This context is your main interface to GPUI, and is used extensively throughout the framework.
+//!
+//! ## Other Resources
+//!
+//! In addition to the systems above, GPUI provides a range of smaller services that are useful for building
+//! complex applications:
+//!
+//! - Actions are user-defined structs that are used for converting keystrokes into logical operations in your UI.
+//!   Use this for implementing keyboard shortcuts, such as cmd-q. See the [`action`] module for more information.
+//! - Platform services, such as `quit the app` or `open a URL` are available as methods on the [`app::AppContext`].
+//! - An async executor that is integrated with the platform's event loop. See the [`executor`] module for more information.,
+//! - The [gpui::test] macro provides a convenient way to write tests for your GPUI applications. Tests also have their
+//!   own kind of context, a [`TestAppContext`] which provides ways of simulating common platform input. See [`app::test_context`]
+//!   and [`test`] modules for more details.
+//!
+//! Currently, the best way to learn about these APIs is to read the Zed source code or to ask us about it at a fireside hack.
+//! We're working on improving the documentation, creating more examples, and will be publishing more guides to GPUI on our [blog](https://zed.dev/blog).
 
 #![deny(missing_docs)]
 #![allow(clippy::type_complexity)]