Finish documenting the action, asset, color, and element modules in GPUI

Remove SmallVec from the public API of GPUI

crates/gpui/src/element.rs

@@ -1,3 +1,39 @@
+//! Elements are the workhorses of GPUI. They are responsible for laying out and painting all of
+//! the contents of a window. Elements form a tree and are laid out according to the web layout
+//! standards as implemented by [taffy](https://github.com/DioxusLabs/taffy). Most of the time,
+//! you won't need to interact with this module or these APIs directly. Elements provide their
+//! own APIs and GPUI, or other element implementation, uses the APIs in this module to convert
+//! that element tree into the pixels you see on the screen.
+//!
+//! # Element Basics
+//!
+//! Elements are constructed by calling [`Render::render()`] on the root view of the window, which
+//! which recursively constructs the element tree from the current state of the application.
+//! These elements are then laid out by Taffy, and painted to the screen according to their own
+//! implementation of [`Element::paint()`]. Before the start of the next frame, the entire element
+//! tree and any callbacks they have registered with GPUI are dropped and the process repeats.
+//!
+//! But some state is too simple and voluminous to store in every view that needs it, e.g.
+//! whether a hover has been started or not. For this, GPUI provides the [`Element::State`], type.
+//! If an element returns an [`ElementId`] from [`IntoElement::element_id()`], and that element id
+//! appears in the same place relative to other views and ElementIds in the frame, then the previous
+//! frame's state will be passed to the element's layout and paint methods.
+//!
+//! # Implementing your own elements
+//!
+//! Elements are intended to be the low level, imperative API to GPUI. They are responsible for upholding,
+//! or breaking, GPUI's features as they deem nescessary. As an example, most GPUI elements are expected
+//! to stay in the bounds that their parent element gives them. But with [`WindowContext::break_content_mask`],
+//! you can ignore this restriction and paint anywhere inside of the window's bounds. This is useful for overlays
+//! and popups and anything else that shows up 'on top' of other elements.
+//! With great power, comes great responsibility.
+//!
+//! However, most of the time, you won't need to implement your own elements. GPUI provides a number of
+//! elements that should cover most common use cases out of the box and it's recommended that you use those.
+//! to construct `components`, using the `RenderOnce` trait and the `#[derive(IntoElement)]` macro. Only implement
+//! components when you need to take manual control of the layout and painting process, such as when using
+//! your own custom layout algorithm or rendering a code editor.
+
 use crate::{
     util::FluentBuilder, ArenaBox, AvailableSpace, BorrowWindow, Bounds, ElementId, LayoutId,
     Pixels, Point, Size, ViewContext, WindowContext, ELEMENT_ARENA,
@@ -7,20 +43,27 @@ pub(crate) use smallvec::SmallVec;
 use std::{any::Any, fmt::Debug};
 
 /// Implemented by types that participate in laying out and painting the contents of a window.
-/// Elements form a tree and are laid out according to web-based layout rules.
-/// Rather than calling methods on implementers of this trait directly, you'll usually call `into_any` to convert  them into an AnyElement, which manages state internally.
-/// You can create custom elements by implementing this trait.
+/// Elements form a tree and are laid out according to web-based layout rules, as implemented by Taffy.
+/// You can create custom elements by implementing this trait, see the module-level documentation
+/// for more details.
 pub trait Element: 'static + IntoElement {
+    /// The type of state to store for this element between frames. See the module-level documentation
+    /// for details.
     type State: 'static;
 
+    /// Before an element can be painted, we need to know where it's going to be and how big it is.
+    /// Use this method to request a layout from Taffy and initialize the element's state.
     fn request_layout(
         &mut self,
         state: Option<Self::State>,
         cx: &mut WindowContext,
     ) -> (LayoutId, Self::State);
 
+    /// Once layout has been completed, this method will be called to paint the element to the screen.
+    /// The state argument is the same state that was returned from [`Element::request_layout()`].
     fn paint(&mut self, bounds: Bounds<Pixels>, state: &mut Self::State, cx: &mut WindowContext);
 
+    /// Convert this element into a dynamically-typed [`AnyElement`].
     fn into_any(self) -> AnyElement {
         AnyElement::new(self)
     }
@@ -29,6 +72,7 @@ pub trait Element: 'static + IntoElement {
 /// Implemented by any type that can be converted into an element.
 pub trait IntoElement: Sized {
     /// The specific type of element into which the implementing type is converted.
+    /// Useful for converting other types into elements automatically, like Strings
     type Element: Element;
 
     /// The [`ElementId`] of self once converted into an [`Element`].
@@ -81,7 +125,10 @@ pub trait IntoElement: Sized {
 
 impl<T: IntoElement> FluentBuilder for T {}
 
+/// An object that can be drawn to the screen. This is the trait that distinguishes `Views` from
+/// models. Views are drawn to the screen and care about the current window's state, models are not and do not.
 pub trait Render: 'static + Sized {
+    /// Render this view into an element tree.
     fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement;
 }
 
@@ -92,35 +139,49 @@ impl Render for () {
 }
 
 /// You can derive [`IntoElement`] on any type that implements this trait.
-/// It is used to allow views to be expressed in terms of abstract data.
+/// It is used to construct reusable `components` out of plain data. Think of
+/// components as a recipe for a certain pattern of elements. RenderOnce allows
+/// you to invoke this pattern, without breaking the fluent builder pattern of
+/// the element APIs.
 pub trait RenderOnce: 'static {
+    /// Render this component into an element tree. Note that this method
+    /// takes ownership of self, as compared to [`Render::render()`] method
+    /// which takes a mutable reference.
     fn render(self, cx: &mut WindowContext) -> impl IntoElement;
 }
 
+/// This is a helper trait to provide a uniform interface for constructing elements that
+/// can accept any number of any kind of child elements
 pub trait ParentElement {
-    fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]>;
+    /// Extend this element's children with the given child elements.
+    fn extend(&mut self, elements: impl Iterator<Item = AnyElement>);
 
+    /// Add a single child element to this element.
     fn child(mut self, child: impl IntoElement) -> Self
     where
         Self: Sized,
     {
-        self.children_mut().push(child.into_element().into_any());
+        self.extend(std::iter::once(child.into_element().into_any()));
         self
     }
 
+    /// Add multiple child elements to this element.
     fn children(mut self, children: impl IntoIterator<Item = impl IntoElement>) -> Self
     where
         Self: Sized,
     {
-        self.children_mut()
-            .extend(children.into_iter().map(|child| child.into_any_element()));
+        self.extend(children.into_iter().map(|child| child.into_any_element()));
         self
     }
 }
 
+/// An element for rendering components. An implementation detail of the [`IntoElement`] derive macro
+/// for [`RenderOnce`]
+#[doc(hidden)]
 pub struct Component<C: RenderOnce>(Option<C>);
 
 impl<C: RenderOnce> Component<C> {
+    /// Create a new component from the given RenderOnce type.
     pub fn new(component: C) -> Self {
         Component(Some(component))
     }
@@ -156,8 +217,9 @@ impl<C: RenderOnce> IntoElement for Component<C> {
     }
 }
 
+/// A globally unique identifier for an element, used to track state across frames.
 #[derive(Deref, DerefMut, Default, Clone, Debug, Eq, PartialEq, Hash)]
-pub struct GlobalElementId(SmallVec<[ElementId; 32]>);
+pub(crate) struct GlobalElementId(SmallVec<[ElementId; 32]>);
 
 trait ElementObject {
     fn element_id(&self) -> Option<ElementId>;
@@ -180,7 +242,8 @@ trait ElementObject {
     );
 }
 
-pub struct DrawableElement<E: Element> {
+/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.
+pub(crate) struct DrawableElement<E: Element> {
     element: Option<E>,
     phase: ElementDrawPhase<E::State>,
 }
@@ -363,10 +426,11 @@ where
     }
 }
 
+/// A dynamically typed element that can be used to store any element type.
 pub struct AnyElement(ArenaBox<dyn ElementObject>);
 
 impl AnyElement {
-    pub fn new<E>(element: E) -> Self
+    pub(crate) fn new<E>(element: E) -> Self
     where
         E: 'static + Element,
         E::State: Any,
@@ -377,10 +441,13 @@ impl AnyElement {
         AnyElement(element)
     }
 
+    /// Request the layout ID of the element stored in this `AnyElement`.
+    /// Used for laying out child elements in a parent element.
     pub fn request_layout(&mut self, cx: &mut WindowContext) -> LayoutId {
         self.0.request_layout(cx)
     }
 
+    /// Paints the element stored in this `AnyElement`.
     pub fn paint(&mut self, cx: &mut WindowContext) {
         self.0.paint(cx)
     }
@@ -404,6 +471,7 @@ impl AnyElement {
         self.0.draw(origin, available_space, cx)
     }
 
+    /// Returns the element ID of the element stored in this `AnyElement`, if any.
     pub fn inner_id(&self) -> Option<ElementId> {
         self.0.element_id()
     }