More doc comments for SparseSet and SparseArray (#23685)

# Objective

The design and purpose of `SparseSet` is not immediately obvious, and
there is very little documentation explaining it.

## Solution

Write more doc comments for `SparseSet` and `SparseArray`.

Author: chescock

crates/bevy_ecs/src/storage/sparse_set.rs

@@ -10,14 +10,37 @@ use bevy_ptr::{OwningPtr, Ptr};
 use core::{cell::UnsafeCell, hash::Hash, marker::PhantomData, num::NonZero, panic::Location};
 use nonmax::{NonMaxU32, NonMaxUsize};
 
+/// A map from `I` to `V` implemented as a `Vec<Option<V>>`.
+///
+/// The key type, `I`, must implement [`SparseSetIndex`]
+/// to allow conversion to and from array indexes.
+///
+/// This supports fast O(1) lookups, since they are simple
+/// array indexing operations with no calculations.
+///
+/// However, it may use a lot of excess memory if the
+/// values are large or the set is sparsely populated.
 #[derive(Debug)]
 pub(crate) struct SparseArray<I, V = I> {
     values: Vec<Option<V>>,
     marker: PhantomData<I>,
 }
 
-/// A space-optimized version of [`SparseArray`] that cannot be changed
-/// after construction.
+/// A map from `I` to `V` implemented as a `Box<[Option<V>]>`.
+///
+/// This uses less space than [`SparseArray`] because it does not
+/// need to store both length and capacity,
+/// but it cannot be changed after construction.
+///
+/// The key type, `I`, must implement [`SparseSetIndex`]
+/// to allow conversion to and from array indexes.
+///
+/// This supports fast O(1) lookups, since they are simple
+/// array indexing operations with no calculations.
+///
+/// However, it may use a lot of excess memory if the
+/// values are large or the set is sparsely populated.
+
 #[derive(Debug)]
 pub(crate) struct ImmutableSparseArray<I, V = I> {
     values: Box<[Option<V>]>,
@@ -445,22 +468,75 @@ impl Drop for ComponentSparseSet {
     }
 }
 
-/// A data structure that blends dense and sparse storage
+/// A map from `I` to `V` that combines dense and sparse storage.
+///
+/// This is implemented as a sparse array mapping keys to dense indexes,
+/// plus dense arrays of indexes and keys.
+///
+/// The key type, `I`, must implement [`SparseSetIndex`]
+/// to allow conversion to and from array indexes.
 ///
-/// `I` is the type of the indices, while `V` is the type of data stored in the dense storage.
+/// This supports fast O(1) lookups, since they consist of one array index to map
+/// the key to a dense index, followed by a second array index to find the value.
+///
+/// This may use a lot of excess memory if the set is sparsely populated,
+/// since it stores an empty entry for each key.
+///
+/// Compared to a simple `Vec<Option<V>>`,
+/// the dense storage of values takes less memory when `V` is large,
+/// although the overhead of tracking which entries have values
+/// may make it larger when `V` is small or the set is densely populated.
 #[derive(Debug)]
 pub struct SparseSet<I, V: 'static> {
+    /// The mapping from dense index to value.
+    ///
+    /// `dense[sparse[k]]` holds the value for `k`.
     dense: Vec<V>,
+
+    /// The reverse mapping from dense index to key.
+    ///
+    /// `indices[sparse[k]] == k`
     indices: Vec<I>,
+
+    /// The mapping from keys to dense indexes.
     sparse: SparseArray<I, NonMaxUsize>,
 }
 
-/// A space-optimized version of [`SparseSet`] that cannot be changed
-/// after construction.
+/// A map from `I` to `V` that combines dense and sparse storage.
+///
+/// This is implemented as a sparse array mapping keys to dense indexes,
+/// plus dense arrays of indexes and keys.
+///
+/// This uses less space than [`SparseSet`] because it does not
+/// need to store both length and capacity,
+/// but it cannot be changed after construction.
+///
+/// The key type, `I`, must implement [`SparseSetIndex`]
+/// to allow conversion to and from array indexes.
+///
+/// This supports fast O(1) lookups, since they consist of one array index to map
+/// the key to a dense index, followed by a second array index to find the value.
+///
+/// This may use a lot of excess memory if the set is sparsely populated,
+/// since it stores an empty entry for each key.
+///
+/// Compared to a simple `Vec<Option<V>>`,
+/// the dense storage of values takes less memory when `V` is large,
+/// although the overhead of tracking which entries have values
+/// may make it larger when `V` is small or the set is densely populated.
 #[derive(Debug)]
 pub(crate) struct ImmutableSparseSet<I, V: 'static> {
+    /// The mapping from dense index to value.
+    ///
+    /// `dense[sparse[k]]` holds the value for `k`.
     dense: Box<[V]>,
+
+    /// The reverse mapping from dense index to key.
+    ///
+    /// `indices[sparse[k]] == k`
     indices: Box<[I]>,
+
+    /// The mapping from keys to dense indexes.
     sparse: ImmutableSparseArray<I, NonMaxUsize>,
 }