@@ -13,0 +15,4 @@
+/// The sparse allocator is mainly used for bulk allocations in the system's page size
+/// for the lookup array. It will also be used for the array of pointers into those
+/// bulk allocations. Additionally it will be used for the reverse map that generates keys
+/// from the value in the internal packed array

@@ -13,0 +21,4 @@
+///
+/// All operations on this datastructure, meaning insertion, lookup, and deletion, are `O(1)`.
+///
+/// This datastructure does not in any way guarantee ordering of the values on

@@ -18,1 +32,4 @@
+    /// The paginated array of keys. The value at the key is an index into the dense array minus 
+    /// one where the value corresponding to that key is stored.
     sparse: Vec<SparsePage<SparseAlloc>, SparseAlloc>,
+    /// The dense array where the values corresponding to the keys are stored

@@ -18,2 +34,4 @@
     sparse: Vec<SparsePage<SparseAlloc>, SparseAlloc>,
+    /// The dense array where the values corresponding to the keys are stored
     dense: Vec<T, PackedAlloc>,
+    /// The reverse map to get the index in the sparse array from the index in the dense array

@@ -52,15 +105,39 @@ where
         }
     }
 
+    /// Gets the value with the key `id`

@@ -84,6 +161,15 @@ where
         }
     }
 
+    /// Gets the index in the dense array for a key `id`

@@ -92,2 +178,4 @@
     }
 
+    /// This reduces the usage count for a page in the sparse array, deallocating 
+    /// it if it is not used anymore

@@ -103,6 +191,7 @@ where
         }
     }
 
+    /// Increase the page usage count for a page in the sparse array

@@ -133,3 +243,4 @@
         self.len() == 0
     }
 
+    /// Returns the number of values in this sparse set

@@ -137,3 +258,4 @@
         self.dense.len()
     }
 
+    /// Checks if the sparse set contains a value with key `id`

@@ -149,3 +315,4 @@
         &self.dense
     }
 
+    /// Mutable version of [`Self::keys`]

@@ -10,17 +10,36 @@ use bytemuck::Contiguous;
 const SPARSE_PAGESIZE: usize = (1 << 10) * 4;
 type SparsePage<A> = Option<(Box<[Option<NonZeroUsize>; SPARSE_PAGESIZE], A>, usize)>;
 
+/// A sparse set for fast lookup of large indices