Improve bevy_ecs query docs (#1935)

Mainly documents Query, WorldQuery and the various Query Filter types as well as some smaller doc changes.

Author: Veykril

crates/bevy_ecs/src/component/mod.rs

@@ -10,19 +10,19 @@ use std::{
 };
 use thiserror::Error;
 
-/// A component is data associated with an `Entity`. Each entity can have multiple different types
-/// of components, but only one of them per type.
+/// A component is data associated with an [`Entity`](crate::entity::Entity). Each entity can have
+/// multiple different types of components, but only one of them per type.
 ///
 /// Any type that is `Send + Sync + 'static` automatically implements `Component`.
 ///
-/// Components are added with new entities using [Commands::spawn](crate::system::Commands::spawn),
-/// or to existing entities with [Commands::insert](crate::system::Commands::insert),
-/// or their [World](crate::world::World) equivalents.
+/// Components are added with new entities using [`Commands::spawn`](crate::system::Commands::spawn),
+/// or to existing entities with [`EntityCommands::insert`](crate::system::EntityCommands::insert),
+/// or their [`World`](crate::world::World) equivalents.
 ///
-/// Components can be accessed in systems by using a [Query](crate::system::Query)
+/// Components can be accessed in systems by using a [`Query`](crate::system::Query)
 /// as one of the arguments.
 ///
-/// Components can be grouped together into a [Bundle](crate::bundle::Bundle).
+/// Components can be grouped together into a [`Bundle`](crate::bundle::Bundle).
 pub trait Component: Send + Sync + 'static {}
 impl<T: Send + Sync + 'static> Component for T {}
 
@@ -241,6 +241,7 @@ impl Components {
     }
 
     /// # Safety
+    ///
     /// `id` must be a valid [ComponentId]
     #[inline]
     pub unsafe fn get_info_unchecked(&self, id: ComponentId) -> &ComponentInfo {

crates/bevy_ecs/src/component/type_info.rs

@@ -1,6 +1,6 @@
 use std::{alloc::Layout, any::TypeId};
 
-/// Metadata required to store a component
+/// Metadata required to store a component.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct TypeInfo {
     type_id: TypeId,
@@ -11,7 +11,7 @@ pub struct TypeInfo {
 }
 
 impl TypeInfo {
-    /// Metadata for `T`
+    /// Metadata for `T`.
     pub fn of<T: Send + Sync + 'static>() -> Self {
         Self {
             type_id: TypeId::of::<T>(),

crates/bevy_ecs/src/entity/mod.rs

@@ -11,28 +11,28 @@ use std::{
     sync::atomic::{AtomicI64, Ordering},
 };
 
-/// Lightweight unique ID of an entity
+/// Lightweight unique ID of an entity.
 ///
-/// Obtained from [World::spawn](crate::world::World::spawn), typically via
-/// [Commands::spawn](crate::system::Commands::spawn). Can be stored to refer to an entity in the
+/// Obtained from [`World::spawn`](crate::world::World::spawn), typically via
+/// [`Commands::spawn`](crate::system::Commands::spawn). Can be stored to refer to an entity in the
 /// future.
 ///
 /// `Entity` can be a part of a query, e.g. `Query<(Entity, &MyComponent)>`.
 /// Components of a specific entity can be accessed using
-/// [Query::get](crate::system::Query::get) and related methods.
+/// [`Query::get`](crate::system::Query::get) and related methods.
 #[derive(Clone, Copy, Hash, Eq, Ord, PartialEq, PartialOrd)]
 pub struct Entity {
     pub(crate) generation: u32,
     pub(crate) id: u32,
 }
 
 impl Entity {
-    /// Creates a new entity reference with a generation of 0
+    /// Creates a new entity reference with a generation of 0.
     pub fn new(id: u32) -> Entity {
         Entity { id, generation: 0 }
     }
 
-    /// Convert to a form convenient for passing outside of rust
+    /// Convert to a form convenient for passing outside of rust.
     ///
     /// Only useful for identifying entities within the same instance of an application. Do not use
     /// for serialization between runs.
@@ -42,7 +42,7 @@ impl Entity {
         u64::from(self.generation) << 32 | u64::from(self.id)
     }
 
-    /// Reconstruct an `Entity` previously destructured with `to_bits`
+    /// Reconstruct an `Entity` previously destructured with [`Entity::to_bits`].
     ///
     /// Only useful when applied to results from `to_bits` in the same instance of an application.
     pub fn from_bits(bits: u64) -> Self {
@@ -52,7 +52,7 @@ impl Entity {
         }
     }
 
-    /// Return a transiently unique identifier
+    /// Return a transiently unique identifier.
     ///
     /// No two simultaneously-live entities share the same ID, but dead entities' IDs may collide
     /// with both live and dead entities. Useful for compactly representing entities within a
@@ -87,7 +87,8 @@ impl SparseSetIndex for Entity {
     }
 }
 
-/// An iterator returning a sequence of Entity values from `Entities::reserve_entities`.
+/// An [`Iterator`] returning a sequence of [`Entity`] values from
+/// [`Entities::reserve_entities`](crate::entity::Entities::reserve_entities).
 pub struct ReserveEntitiesIterator<'a> {
     // Metas, so we can recover the current generation for anything in the freelist.
     meta: &'a [EntityMeta],
@@ -165,7 +166,7 @@ pub struct Entities {
 }
 
 impl Entities {
-    /// Reserve entity IDs concurrently
+    /// Reserve entity IDs concurrently.
     ///
     /// Storage for entity generation and location is lazily allocated by calling `flush`.
     pub fn reserve_entities(&self, count: u32) -> ReserveEntitiesIterator {
@@ -207,7 +208,7 @@ impl Entities {
         }
     }
 
-    /// Reserve one entity ID concurrently
+    /// Reserve one entity ID concurrently.
     ///
     /// Equivalent to `self.reserve_entities(1).next().unwrap()`, but more efficient.
     pub fn reserve_entity(&self) -> Entity {
@@ -240,7 +241,7 @@ impl Entities {
         );
     }
 
-    /// Allocate an entity ID directly
+    /// Allocate an entity ID directly.
     ///
     /// Location should be written immediately.
     pub fn alloc(&mut self) -> Entity {
@@ -261,7 +262,7 @@ impl Entities {
         }
     }
 
-    /// Allocate a specific entity ID, overwriting its generation
+    /// Allocate a specific entity ID, overwriting its generation.
     ///
     /// Returns the location of the entity currently using the given ID, if any. Location should be
     /// written immediately.
@@ -293,7 +294,7 @@ impl Entities {
         loc
     }
 
-    /// Destroy an entity, allowing it to be reused
+    /// Destroy an entity, allowing it to be reused.
     ///
     /// Must not be called while reserved entities are awaiting `flush()`.
     pub fn free(&mut self, entity: Entity) -> Option<EntityLocation> {
@@ -315,7 +316,7 @@ impl Entities {
         Some(loc)
     }
 
-    /// Ensure at least `n` allocations can succeed without reallocating
+    /// Ensure at least `n` allocations can succeed without reallocating.
     pub fn reserve(&mut self, additional: u32) {
         self.verify_flushed();
 
@@ -340,7 +341,7 @@ impl Entities {
         *self.free_cursor.get_mut() = 0;
     }
 
-    /// Access the location storage of an entity
+    /// Access the location storage of an entity.
     ///
     /// Must not be called on pending entities.
     pub fn get_mut(&mut self, entity: Entity) -> Option<&mut EntityLocation> {
@@ -352,7 +353,7 @@ impl Entities {
         }
     }
 
-    /// Returns `Ok(Location { archetype: 0, index: undefined })` for pending entities
+    /// Returns `Ok(Location { archetype: 0, index: undefined })` for pending entities.
     pub fn get(&self, entity: Entity) -> Option<EntityLocation> {
         if (entity.id as usize) < self.meta.len() {
             let meta = &self.meta[entity.id as usize];
@@ -368,6 +369,7 @@ impl Entities {
     /// Panics if the given id would represent an index outside of `meta`.
     ///
     /// # Safety
+    ///
     /// Must only be called for currently allocated `id`s.
     pub unsafe fn resolve_unknown_gen(&self, id: u32) -> Entity {
         let meta_len = self.meta.len();
@@ -463,7 +465,7 @@ impl EntityMeta {
     };
 }
 
-/// A location of an entity in an archetype
+/// A location of an entity in an archetype.
 #[derive(Copy, Clone, Debug)]
 pub struct EntityLocation {
     /// The archetype index

crates/bevy_ecs/src/event.rs

@@ -69,7 +69,7 @@ enum State {
 ///
 /// [`Events::update_system`] is a system that does this, typically intialized automatically using
 /// [`AppBuilder::add_event`]. [EventReader]s are expected to read events from this collection at
-/// least once per loop/frame.  
+/// least once per loop/frame.
 /// Events will persist across a single frame boundary and so ordering of event producers and
 /// consumers is not critical (although poorly-planned ordering may cause accumulating lag).
 /// If events are not handled by the end of the frame after they are updated, they will be
@@ -116,6 +116,8 @@ enum State {
 /// when events are cleared.
 /// This complicates consumption and risks ever-expanding memory usage if not cleaned up,
 /// but can be done by adding your event as a resource instead of using [`AppBuilder::add_event`].
+///
+/// [`AppBuilder::add_event`]: https://docs.rs/bevy/*/bevy/app/struct.AppBuilder.html#method.add_event
 #[derive(Debug)]
 pub struct Events<T> {
     events_a: Vec<EventInstance<T>>,

crates/bevy_ecs/src/query/access.rs

@@ -2,6 +2,9 @@ use crate::storage::SparseSetIndex;
 use fixedbitset::FixedBitSet;
 use std::marker::PhantomData;
 
+/// `Access` keeps track of read and write accesses to values within a collection.
+///
+/// This is used for ensuring systems are executed soundly.
 #[derive(Debug, Eq, PartialEq, Clone)]
 pub struct Access<T: SparseSetIndex> {
     reads_all: bool,
@@ -28,18 +31,21 @@ impl<T: SparseSetIndex> Access<T> {
         self.writes.grow(bits);
     }
 
+    /// Adds a read access for the given index.
     pub fn add_read(&mut self, index: T) {
         self.reads_and_writes.grow(index.sparse_set_index() + 1);
         self.reads_and_writes.insert(index.sparse_set_index());
     }
 
+    /// Adds a write access for the given index.
     pub fn add_write(&mut self, index: T) {
         self.reads_and_writes.grow(index.sparse_set_index() + 1);
         self.writes.grow(index.sparse_set_index() + 1);
         self.reads_and_writes.insert(index.sparse_set_index());
         self.writes.insert(index.sparse_set_index());
     }
 
+    /// Returns true if this `Access` contains a read access for the given index.
     pub fn has_read(&self, index: T) -> bool {
         if self.reads_all {
             true
@@ -48,30 +54,39 @@ impl<T: SparseSetIndex> Access<T> {
         }
     }
 
+    /// Returns true if this `Access` contains a write access for the given index.
     pub fn has_write(&self, index: T) -> bool {
         self.writes.contains(index.sparse_set_index())
     }
 
+    /// Sets this `Access` to having read access for all indices.
     pub fn read_all(&mut self) {
         self.reads_all = true;
     }
 
+    /// Returns true if this `Access` has read access to all indices.
     pub fn reads_all(&self) -> bool {
         self.reads_all
     }
 
+    /// Clears all recorded accesses.
     pub fn clear(&mut self) {
         self.reads_all = false;
         self.reads_and_writes.clear();
         self.writes.clear();
     }
 
+    /// Extends this `Access` with another, copying all accesses of `other` into this.
     pub fn extend(&mut self, other: &Access<T>) {
         self.reads_all = self.reads_all || other.reads_all;
         self.reads_and_writes.union_with(&other.reads_and_writes);
         self.writes.union_with(&other.writes);
     }
 
+    /// Returns true if this `Access` is compatible with `other`.
+    ///
+    /// Two `Access` instances are incompatible with each other if one `Access` has a write for
+    /// which the other also has a write or a read.
     pub fn is_compatible(&self, other: &Access<T>) -> bool {
         if self.reads_all {
             0 == other.writes.count_ones(..)
@@ -83,6 +98,7 @@ impl<T: SparseSetIndex> Access<T> {
         }
     }
 
+    /// Calculates conflicting accesses between this `Access` and `other`.
     pub fn get_conflicts(&self, other: &Access<T>) -> Vec<T> {
         let mut conflicts = FixedBitSet::default();
         if self.reads_all {