Fix docs

Author: james7132

crates/bevy_ecs/src/archetype.rs

@@ -417,7 +417,7 @@ impl Archetype {
                 },
             );
             // NOTE: the `table_components` are sorted AND they were inserted in the `Table` in the same
-            // sorted order, so the index of the `Column` in the `Table` is the same as the index of the
+            // sorted order, so the index of the `ThinColumn` in the `Table` is the same as the index of the
             // component in the `table_components` vector
             component_index
                 .entry(component_id)

crates/bevy_ecs/src/storage/blob_array.rs

@@ -3,12 +3,13 @@ use bevy_ptr::{OwningPtr, Ptr, PtrMut};
 use bevy_utils::OnDrop;
 use core::{alloc::Layout, cell::UnsafeCell, num::NonZeroUsize, ptr::NonNull};
 
-/// A flat, type-erased data storage type similar to a [`BlobVec`](super::blob_vec::BlobVec), but with the length and capacity cut out
-/// for performance reasons. This type is reliant on its owning type to store the capacity and length information.
+/// A flat, type-erased data storage type.
 ///
 /// Used to densely store homogeneous ECS data. A blob is usually just an arbitrary block of contiguous memory without any identity, and
-/// could be used to represent any arbitrary data (i.e. string, arrays, etc). This type only stores meta-data about the Blob that it stores,
-/// and a pointer to the location of the start of the array, similar to a C array.
+/// could be used to represent any arbitrary data (i.e. string, arrays, etc). This type only stores meta-data about the blob that it stores,
+/// and a pointer to the location of the start of the array, similar to a C-style `void*` array.
+///
+/// for performance reasons. This type is reliant on its owning type to store the capacity and length information.
 #[derive(Debug)]
 pub(super) struct BlobArray {
     item_layout: Layout,
@@ -78,7 +79,7 @@ impl BlobArray {
     /// Returns a reference to the element at `index`, without doing bounds checking.
     ///
     /// *`len` refers to the length of the array, the number of elements that have been initialized, and are safe to read.
-    /// Just like [`Vec::len`], or [`BlobVec::len`](super::blob_vec::BlobVec::len).*
+    /// Just like [`Vec::len`].*
     ///
     /// # Safety
     /// - The element at index `index` is safe to access.
@@ -101,7 +102,7 @@ impl BlobArray {
     /// Returns a mutable reference to the element at `index`, without doing bounds checking.
     ///
     /// *`len` refers to the length of the array, the number of elements that have been initialized, and are safe to read.
-    /// Just like [`Vec::len`], or [`BlobVec::len`](super::blob_vec::BlobVec::len).*
+    /// Just like [`Vec::len`].*
     ///
     /// # Safety
     /// - The element with at index `index` is safe to access.
@@ -139,7 +140,7 @@ impl BlobArray {
     /// To get a slice to the entire array, the caller must plug `len` in `slice_len`.
     ///
     /// *`len` refers to the length of the array, the number of elements that have been initialized, and are safe to read.
-    /// Just like [`Vec::len`], or [`BlobVec::len`](super::blob_vec::BlobVec::len).*
+    /// Just like [`Vec::len`].*
     ///
     /// # Safety
     /// - The type `T` must be the type of the items in this [`BlobArray`].

crates/bevy_ecs/src/storage/resource.rs

@@ -56,7 +56,7 @@ impl<const SEND: bool> Drop for ResourceData<SEND> {
 }
 
 impl<const SEND: bool> ResourceData<SEND> {
-    /// The only row in the underlying `BlobVec`.
+    /// The only row in the underlying `BlobArray`.
     const ROW: usize = 0;
 
     /// Validates the access to `!Send` resources is only done on the thread they were created from.

crates/bevy_ecs/src/storage/table/column.rs

@@ -5,13 +5,22 @@ use crate::{
 };
 use core::panic::Location;
 
-/// Very similar to a normal [`Column`], but with the capacities and lengths cut out for performance reasons.
+/// A type-erased contiguous container for data of a homogeneous type.
 ///
-/// This type is used by [`Table`], because all of the capacities and lengths of the [`Table`]'s columns must match.
+/// Conceptually, a `ThinColumn` is very similar to a type-erased `Box<[T]>`.
+/// It also stores the change detection ticks for its components, kept in two separate
+/// contiguous buffers internally. An element shares its data across these buffers by using the
+/// same index (i.e. the entity at row 3 has it's data at index 3 and its change detection ticks at index 3).
 ///
-/// Like many other low-level storage types, [`ThinColumn`] has a limited and highly unsafe
+/// Like many other low-level storage types, `ThinColumn` has a limited and highly unsafe
 /// interface. It's highly advised to use higher level types and their safe abstractions
-/// instead of working directly with [`ThinColumn`].
+/// instead of working directly with `ThinColumn`.
+///
+/// For performance reasons, `ThinColumn` does not does not store it's capacity and length.
+/// This type is used by [`Table`] and [`ComponentSparseSet`], because all of the capacities
+/// and lengths of the owning storaage.
+///
+/// [`ComponentSparseSet`]: crate::storage::ComponentSparseSet
 #[derive(Debug)]
 pub struct ThinColumn {
     pub(super) data: BlobArray,
@@ -351,7 +360,7 @@ impl ThinColumn {
             .map(|changed_by| changed_by.as_slice(len))
     }
 
-    /// Fetches a read-only reference to the data at `row`. Unlike [`Column::get`] this does not
+    /// Fetches a read-only reference to the data at `row`. This does not
     /// do any bounds checking.
     ///
     /// # Safety
@@ -364,7 +373,7 @@ impl ThinColumn {
 
     /// Fetches the calling location that last changed the value at `row`.
     ///
-    /// Unlike [`Column::get_changed_by`] this function does not do any bounds checking.
+    /// This function does not do any bounds checking.
     ///
     /// # Safety
     /// `row` must be within the range `[0, self.len())`.
@@ -378,8 +387,8 @@ impl ThinColumn {
             .map(|changed_by| changed_by.get_unchecked(row.index()))
     }
 
-    /// Fetches the "added" change detection tick for the value at `row`. Unlike [`Column::get_added_tick`]
-    /// this function does not do any bounds checking.
+    /// Fetches the "added" change detection tick for the value at `row`.
+    /// This function does not do any bounds checking.
     ///
     /// # Safety
     /// `row` must be within the range `[0, self.len())`.
@@ -388,8 +397,8 @@ impl ThinColumn {
         self.added_ticks.get_unchecked(row.index())
     }
 
-    /// Fetches the "changed" change detection tick for the value at `row`. Unlike [`Column::get_changed_tick`]
-    /// this function does not do any bounds checking.
+    /// Fetches the "changed" change detection tick for the value at `row`
+    /// This function does not do any bounds checking.
     ///
     /// # Safety
     /// `row` must be within the range `[0, self.len())`.
@@ -398,8 +407,8 @@ impl ThinColumn {
         self.changed_ticks.get_unchecked(row.index())
     }
 
-    /// Fetches the change detection ticks for the value at `row`. Unlike [`Column::get_ticks`]
-    /// this function does not do any bounds checking.
+    /// Fetches the change detection ticks for the value at `row`.
+    /// This function does not do any bounds checking.
     ///
     /// # Safety
     /// `row` must be within the range `[0, self.len())`.