Add a bunch of docs

Co-Authored-By: Conrad <conrad@zed.dev>
Co-Authored-By: Mikayla <mikayla@zed.dev>

crates/gpui/src/test.rs

@@ -1,3 +1,30 @@
+//! Test support for GPUI.
+//!
+//! GPUI provides first-class support for testing, which includes a macro to run test that rely on having a context,
+//! and a test implementation of the `ForegroundExecutor` and `BackgroundExecutor` which ensure that your tests run
+//! deterministically even in the face of arbitrary parallelism.
+//!
+//! The output of the `gpui::test` macro is understood by other rust test runners, so you can use it with `cargo test`
+//! or `cargo-nextest`, or another runner of your choice.
+//!
+//! To make it possible to test collaborative user interfaces (like Zed) you can ask for as many different contexts
+//! as you need.
+//!
+//! ## Example
+//!
+//! ```
+//! use gpui;
+//!
+//! #[gpui::test]
+//! async fn test_example(cx: &TestAppContext) {
+//!   assert!(true)
+//! }
+//!
+//! #[gpui::test]
+//! async fn test_collaboration_example(cx_a: &TestAppContext, cx_b: &TestAppContext) {
+//!   assert!(true)
+//! }
+//! ```
 use crate::{Entity, Subscription, TestAppContext, TestDispatcher};
 use futures::StreamExt as _;
 use rand::prelude::*;
@@ -68,6 +95,7 @@ impl<T: 'static> futures::Stream for Observation<T> {
     }
 }
 
+/// observe returns a stream of the change events from the given `View` or `Model`
 pub fn observe<T: 'static>(entity: &impl Entity<T>, cx: &mut TestAppContext) -> Observation<()> {
     let (tx, rx) = smol::channel::unbounded();
     let _subscription = cx.update(|cx| {