From 48c6727810aee19bba8c91309393d382e613b60f Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Sat, 18 Dec 2021 15:10:44 -0500
Subject: [PATCH] Extremely basic docs for Storages

---
 crates/bevy_ecs/src/storage/blob_vec.rs   | 5 ++++-
 crates/bevy_ecs/src/storage/mod.rs        | 1 +
 crates/bevy_ecs/src/storage/sparse_set.rs | 9 +++++++++
 crates/bevy_ecs/src/storage/table.rs      | 3 +++
 4 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/crates/bevy_ecs/src/storage/blob_vec.rs b/crates/bevy_ecs/src/storage/blob_vec.rs
index f6b890e7be2e4..5592c9a903829 100644
--- a/crates/bevy_ecs/src/storage/blob_vec.rs
+++ b/crates/bevy_ecs/src/storage/blob_vec.rs
@@ -3,6 +3,9 @@ use std::{
     ptr::NonNull,
 };
 
+/// A flat, type-erased data storage type
+///
+/// Used to densely store homogeneous ECS data.
 #[derive(Debug)]
 pub struct BlobVec {
     item_layout: Layout,
@@ -122,7 +125,7 @@ impl BlobVec {
         self.len = old_len;
     }
 
-    /// increases the length by one (and grows the vec if needed) with uninitialized memory and
+    /// Increases the length by one (and grows the vec if needed) with uninitialized memory and
     /// returns the index
     ///
     /// # Safety
diff --git a/crates/bevy_ecs/src/storage/mod.rs b/crates/bevy_ecs/src/storage/mod.rs
index 26f92fdf8808b..f54a2275bfe07 100644
--- a/crates/bevy_ecs/src/storage/mod.rs
+++ b/crates/bevy_ecs/src/storage/mod.rs
@@ -8,6 +8,7 @@ pub use blob_vec::*;
 pub use sparse_set::*;
 pub use table::*;
 
+/// The raw data stores of a [World](crate::world::World)
 #[derive(Default)]
 pub struct Storages {
     pub sparse_sets: SparseSets,
diff --git a/crates/bevy_ecs/src/storage/sparse_set.rs b/crates/bevy_ecs/src/storage/sparse_set.rs
index 8ad76046e6cdc..ef0ab475507a2 100644
--- a/crates/bevy_ecs/src/storage/sparse_set.rs
+++ b/crates/bevy_ecs/src/storage/sparse_set.rs
@@ -88,6 +88,9 @@ impl<I: SparseSetIndex, V> SparseArray<I, V> {
     }
 }
 
+/// A sparse data structure of [Components](crate::component::Component)
+///
+/// Designed for relatively fast insertions and deletions.
 #[derive(Debug)]
 pub struct ComponentSparseSet {
     dense: BlobVec,
@@ -228,6 +231,9 @@ impl ComponentSparseSet {
     }
 }
 
+/// A data structure that blends dense and sparse storage
+///
+/// `I` is the type of the indices, while `V` is the type of data stored in the dense storage.
 #[derive(Debug)]
 pub struct SparseSet<I, V: 'static> {
     dense: Vec<V>,
@@ -391,6 +397,9 @@ macro_rules! impl_sparse_set_index {
 
 impl_sparse_set_index!(u8, u16, u32, u64, usize);
 
+/// A collection of [ComponentSparseSet] storages, indexed by [ComponentId]
+///
+/// Can be accessed via [Storages](crate::storage::Storages)
 #[derive(Default)]
 pub struct SparseSets {
     sets: SparseSet<ComponentId, ComponentSparseSet>,
diff --git a/crates/bevy_ecs/src/storage/table.rs b/crates/bevy_ecs/src/storage/table.rs
index 3f9a0b38b4f38..d4bd5b471f1b9 100644
--- a/crates/bevy_ecs/src/storage/table.rs
+++ b/crates/bevy_ecs/src/storage/table.rs
@@ -410,6 +410,9 @@ impl Table {
     }
 }
 
+/// A collection of [Table] storages, indexed by [TableId]
+///
+/// Can be accessed via [Storages](crate::storage::Storages)
 pub struct Tables {
     tables: Vec<Table>,
     table_ids: HashMap<u64, TableId>,