From 280d094f67f0de7856d81cd836f744147fde0c66 Mon Sep 17 00:00:00 2001
From: Evan Almloff <evanalmloff@gmail.com>
Date: Mon, 7 Aug 2023 17:32:25 -0700
Subject: [PATCH] document generational box

---
 packages/generational-box/README.md  | 34 ++++++++++++++++++++++++++++
 packages/generational-box/src/lib.rs |  3 +++
 2 files changed, 37 insertions(+)
 create mode 100644 packages/generational-box/README.md

diff --git a/packages/generational-box/README.md b/packages/generational-box/README.md
new file mode 100644
index 000000000..d4600dd53
--- /dev/null
+++ b/packages/generational-box/README.md
@@ -0,0 +1,34 @@
+# Generational Box
+
+Generational Box is a runtime for Rust that allows any static type to implement `Copy`. It can be combined with a global runtime to create an ergonomic state solution like `dioxus-signals`. This crate contains no `unsafe` code.
+
+There are three main types that manage state in Generational Box:
+
+- Store: Handles recycling generational boxes that have been dropped. Your application should have one store or one store per thread.
+- Owner: Handles dropping generational boxes. The owner acts like a runtime lifetime guard. Any states that you create with an owner will be dropped when that owner is dropped.
+- GenerationalBox: The core Copy state type. The generational box will be dropped when the owner is dropped.
+
+Example:
+
+```rust
+// Create a store for this thread
+let store = Store::default();
+
+{
+    // Create an owner for some state for a scope
+    let owner = store.owner();
+
+    // Create some non-copy data, move it into a owner, and work with copy data
+    let data: String = "hello world".to_string();
+    let key = owner.insert(data);
+    
+    // The generational box can be read from and written to like a RefCell
+    let value = key.read();
+    assert_eq!(*value, "hello world");
+}
+// Reading value at this point will cause a panic
+```
+
+## How it works
+
+Internally 
\ No newline at end of file
diff --git a/packages/generational-box/src/lib.rs b/packages/generational-box/src/lib.rs
index d45701e6c..dedd62d75 100644
--- a/packages/generational-box/src/lib.rs
+++ b/packages/generational-box/src/lib.rs
@@ -145,6 +145,7 @@ fn fuzz() {
     }
 }
 
+/// The core Copy state type. The generational box will be dropped when the [Owner] is dropped.
 pub struct GenerationalBox<T> {
     raw: MemoryLocation,
     #[cfg(any(debug_assertions, feature = "check_generation"))]
@@ -268,6 +269,7 @@ impl MemoryLocation {
     }
 }
 
+/// Handles recycling generational boxes that have been dropped. Your application should have one store or one store per thread.
 #[derive(Clone)]
 pub struct Store {
     bump: &'static Bump,
@@ -310,6 +312,7 @@ impl Store {
     }
 }
 
+/// Owner: Handles dropping generational boxes. The owner acts like a runtime lifetime guard. Any states that you create with an owner will be dropped when that owner is dropped.
 pub struct Owner {
     store: Store,
     owned: Rc<RefCell<Vec<MemoryLocation>>>,