From 7a299e966afeb9eb5f0940ad9f22cdfcaa886a4c Mon Sep 17 00:00:00 2001
From: Mikayla <mikayla@zed.dev>
Date: Wed, 17 Jan 2024 10:21:29 -0800
Subject: [PATCH] Document view crate

co-authored-by: Nathan <nathan@zed.dev>
---
 crates/gpui/src/view.rs | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/crates/gpui/src/view.rs b/crates/gpui/src/view.rs
index 968fbbd94c..3701bbbd69 100644
--- a/crates/gpui/src/view.rs
+++ b/crates/gpui/src/view.rs
@@ -1,3 +1,5 @@
+#![deny(missing_docs)]
+
 use crate::{
     seal::Sealed, AnyElement, AnyModel, AnyWeakModel, AppContext, AvailableSpace, BorrowWindow,
     Bounds, ContentMask, Element, ElementId, Entity, EntityId, Flatten, FocusHandle, FocusableView,
@@ -11,12 +13,16 @@ use std::{
     hash::{Hash, Hasher},
 };
 
+/// A view is a piece of state that can be presented on screen by implementing the [Render] trait.
+/// Views implement [Element] and can composed with other views, and every window is created with a root view.
 pub struct View<V> {
+    /// A view is just a [Model] whose type implements `Render`, and the model is accessible via this field.
     pub model: Model<V>,
 }
 
 impl<V> Sealed for View<V> {}
 
+#[doc(hidden)]
 pub struct AnyViewState {
     root_style: Style,
     cache_key: Option<ViewCacheKey>,
@@ -58,6 +64,7 @@ impl<V: 'static> View<V> {
         Entity::downgrade(self)
     }
 
+    /// Update the view's state with the given function, which is passed a mutable reference and a context.
     pub fn update<C, R>(
         &self,
         cx: &mut C,
@@ -69,10 +76,12 @@ impl<V: 'static> View<V> {
         cx.update_view(self, f)
     }
 
+    /// Obtain a read-only reference to this view's state.
     pub fn read<'a>(&self, cx: &'a AppContext) -> &'a V {
         self.model.read(cx)
     }
 
+    /// Gets a [FocusHandle] for this view when its state implements [FocusableView].
     pub fn focus_handle(&self, cx: &AppContext) -> FocusHandle
     where
         V: FocusableView,
@@ -131,19 +140,24 @@ impl<V> PartialEq for View<V> {
 
 impl<V> Eq for View<V> {}
 
+/// A weak variant of [View] which does not prevent the view from being released.
 pub struct WeakView<V> {
     pub(crate) model: WeakModel<V>,
 }
 
 impl<V: 'static> WeakView<V> {
+    /// Gets the entity id associated with this handle.
     pub fn entity_id(&self) -> EntityId {
         self.model.entity_id
     }
 
+    /// Obtain a strong handle for the view if it hasn't been released.
     pub fn upgrade(&self) -> Option<View<V>> {
         Entity::upgrade_from(self)
     }
 
+    /// Update this view's state if it hasn't been released.
+    /// Returns an error if this view has been released.
     pub fn update<C, R>(
         &self,
         cx: &mut C,
@@ -157,9 +171,10 @@ impl<V: 'static> WeakView<V> {
         Ok(view.update(cx, f)).flatten()
     }
 
+    /// Assert that the view referenced by this handle has been released.
     #[cfg(any(test, feature = "test-support"))]
-    pub fn assert_dropped(&self) {
-        self.model.assert_dropped()
+    pub fn assert_released(&self) {
+        self.model.assert_released()
     }
 }
 
@@ -185,6 +200,7 @@ impl<V> PartialEq for WeakView<V> {
 
 impl<V> Eq for WeakView<V> {}
 
+/// A dynically-typed handle to a view, which can be downcast to a [View] for a specific type.
 #[derive(Clone, Debug)]
 pub struct AnyView {
     model: AnyModel,
@@ -193,11 +209,15 @@ pub struct AnyView {
 }
 
 impl AnyView {
+    /// Indicate that this view should be cached when using it as an element.
+    /// When using this method, the view's previous layout and paint will be recycled from the previous frame if [ViewContext::notify] has not been called since it was rendered.
+    /// The one exception is when [WindowContext::refresh] is called, in which case caching is ignored.
     pub fn cached(mut self) -> Self {
         self.cache = true;
         self
     }
 
+    /// Convert this to a weak handle.
     pub fn downgrade(&self) -> AnyWeakView {
         AnyWeakView {
             model: self.model.downgrade(),
@@ -205,6 +225,8 @@ impl AnyView {
         }
     }
 
+    /// Convert this to a [View] of a specific type.
+    /// If this handle does not contain a view of the specified type, returns itself in an `Err` variant.
     pub fn downcast<T: 'static>(self) -> Result<View<T>, Self> {
         match self.model.downcast() {
             Ok(model) => Ok(View { model }),
@@ -216,10 +238,12 @@ impl AnyView {
         }
     }
 
+    /// Gets the [TypeId] of the underlying view.
     pub fn entity_type(&self) -> TypeId {
         self.model.entity_type
     }
 
+    /// Gets the entity id of this handle.
     pub fn entity_id(&self) -> EntityId {
         self.model.entity_id()
     }
@@ -337,12 +361,14 @@ impl IntoElement for AnyView {
     }
 }
 
+/// A weak, dynamically-typed view handle that does not prevent the view from being released.
 pub struct AnyWeakView {
     model: AnyWeakModel,
     layout: fn(&AnyView, &mut WindowContext) -> (LayoutId, AnyElement),
 }
 
 impl AnyWeakView {
+    /// Convert to a strongly-typed handle if the referenced view has not yet been released.
     pub fn upgrade(&self) -> Option<AnyView> {
         let model = self.model.upgrade()?;
         Some(AnyView {