clean up docs.

crates/bevy_ecs/src/query/access.rs

@@ -224,7 +224,7 @@ impl<T: SparseSetIndex> Access<T> {
         reads.is_subset(&other.reads_and_writes) && self.writes.is_subset(&other.writes)
     }
 
-    /// modifies self with the intersection with `other`
+    /// Modify `self` with the intersection with `other`
     pub fn intersect(&mut self, other: &Access<T>) {
         if self.writes_all {
             if other.writes_all {
@@ -317,7 +317,7 @@ impl<T: SparseSetIndex> Access<T> {
         self.writes.ones().map(T::get_sparse_set_index)
     }
 
-    /// Returns true if the difference of `self` with `other` is empty
+    /// Returns `true` if the difference of `self` with `other` is empty
     pub fn read_and_writes_difference_is_empty(&self, other: &Access<T>) -> bool {
         if self.reads_all || self.writes_all {
             return other.reads_all || other.writes_all;
@@ -458,12 +458,12 @@ impl<T: SparseSetIndex> FilteredAccess<T> {
         })
     }
 
-    /// `other` contains all the same access as `self`.  This does not take into account the filtered access.
+    /// `other` contains all the same access as `self`.  This does not take into account the `filter_sets`.
     pub fn is_subset(&self, other: &FilteredAccess<T>) -> bool {
         self.access.is_subset(&other.access)
     }
 
-    /// returns true if optional access has not changed
+    /// Returns `true` if optional access has not changed.
     pub fn is_optional_compatible(
         &self,
         mut original_optional: Access<T>,

crates/bevy_ecs/src/query/fetch.rs

@@ -437,9 +437,8 @@ pub unsafe trait WorldQuery {
         access: &mut Access<ArchetypeComponentId>,
     );
 
-    /// Adds component access for when [`WorldQuery`] is not an exact match.
-    /// i.e. Option<&T> where the matched archetypes don't necessarily contain
-    /// the data the [`WorldQuery`] takes access to in [`Self::update_component_access`]
+    /// Adds component access to `access` for when [`WorldQuery`] is not an exact match.
+    /// i.e. With `Option<&T>` the matched archetypes do not necessarily contain a `T`.
     fn optional_access(
         state: &Self::State,
         access: &mut Access<ComponentId>,
@@ -449,8 +448,9 @@ pub unsafe trait WorldQuery {
     /// Creates and initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type.
     fn init_state(world: &mut World) -> Self::State;
 
-    /// Creates a [`State`](WorldQuery::State) for this [`WorldQuery`] type. This should return
-    /// the same value as [`init_state`](Self::init_state).
+    /// Creates a [`State`](WorldQuery::State) for this [`WorldQuery`] type. When successful, this returns
+    /// the same value as [`init_state`](Self::init_state). When the state cannot be created, this return `None`.
+    /// This might happen if we try to get the state for a component has not been registered in the [`World`].
     fn get_state(components: &Components) -> Option<Self::State>;
 
     /// Returns `true` if this query matches a set of components. Otherwise, returns `false`.
@@ -1854,7 +1854,6 @@ unsafe impl<T: ?Sized> WorldQuery for PhantomData<T> {
     const IS_DENSE: bool = true;
     // `PhantomData` matches every entity in each archetype.
     const IS_ARCHETYPAL: bool = true;
-    // `PhantomData` does not access any data, so it is exact.
 
     unsafe fn set_archetype<'w>(
         _fetch: &mut Self::Fetch<'w>,

crates/bevy_ecs/src/query/state.rs

@@ -138,13 +138,14 @@ impl<Q: WorldQuery, F: ReadOnlyWorldQuery> QueryState<Q, F> {
         state
     }
 
-    /// This is used to transform a [`Query`](crate::system::Query) into a more generic [`Query`](crate::system::Query).
-    /// This can be useful for passsing to another function tha might take the more generalize query.
+    /// Use this to transform a [`QueryState`] into a more generic [`QueryState`].
+    /// This can be useful for passing to another function that might take the more general form.
     /// See [`Query::transmute_fetch`](crate::system::Query::transmute_fetch) for more details.
     ///
     /// You should not call [`update_archetypes`](Self::update_archetypes) on the returned [`QueryState`] as the result will be unpredictable.
     /// You might end up with a mix of archetypes that only matched the original query + archetypes that only match
-    /// the new [`QueryState`]. Most of the safe methods on [`QueryState`] call [`QueryState::update_archetypes`] internally.
+    /// the new [`QueryState`]. Most of the safe methods on [`QueryState`] call [`QueryState::update_archetypes`] internally, so this
+    /// best used through a [`Query`](crate::system::Query).
     #[track_caller]
     pub(crate) fn transmute_fetch<NewQ: WorldQuery>(
         &self,
@@ -157,7 +158,7 @@ impl<Q: WorldQuery, F: ReadOnlyWorldQuery> QueryState<Q, F> {
             "Could not create fetch_state. Please initialize any components needed before trying to `transmute`",
         );
         #[allow(clippy::let_unit_value)]
-        // the archetypal filters have already been applied, so we don't need them.
+        // the archetypal filters have already been applied, so we discard them to make the query type more general.
         let filter_state = <()>::get_state(components).expect(
             "Could not create filter_state. Please initialize any components needed before trying to `transmute`",
         );

crates/bevy_ecs/src/system/query.rs

@@ -400,13 +400,17 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> Query<'w, 's, Q, F> {
         }
     }
 
-    /// Returns a [`QueryLens`] that can be used to get a query with a more restricted fetch.
-    /// i.e. Tranform a `Query<(&A, &mut B)>` to a `Query<&B>`.
-    /// This can be useful for passing the query to another function.
+    /// Returns a [`QueryLens`] that can be used to get a query with a more general fetch.
+    /// For example, this can transform a `Query<(&A, &mut B)>` to a `Query<&B>`.
+    /// This can be useful for passing the query to another function. Note that this will
+    /// not return all the entities in the world that match the new query. This will only
+    /// return the entities that matched the original query.
     ///
     /// ## Panics
     ///
-    /// This will panic if `NewQ` is not a subset of `Q` or if `F` includes `Added` or `Changed`.
+    /// This will panic if `NewQ` is not a subset of the original fetch `Q`
+    /// or if the original filter `F` includes [`Added`](crate::query::Added) or
+    /// [`Changed`](crate::query::Changed).
     ///
     /// ## Example
     ///
@@ -423,24 +427,39 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> Query<'w, 's, Q, F> {
     /// # let mut world = World::new();
     /// #
     /// # world.spawn((A(10), B(5)));
-    ///
-    /// fn function_that_uses_a_query_lens(lens: &mut QueryLens<&A>) {
+    /// #
+    /// fn reusable_function(lens: &mut QueryLens<&A>) {
     ///     assert_eq!(lens.query().single().0, 10);
     /// }
     ///
+    /// // We can use the function in a system that takes the exact query.
     /// fn system_1(mut query: Query<&A>) {
-    ///     function_that_uses_a_query_lens(&mut query.into_query_lens());
+    ///     reusable_function(&mut query.into_query_lens());
     /// }
     ///
+    /// // We can also use it with a query that does not match exactly
+    /// // by transmuting it.
     /// fn system_2(mut query: Query<(&mut A, &B)>) {
     ///     let mut lens = query.transmute_fetch::<&A>();
-    ///     function_that_uses_a_query_lens(&mut lens);
+    ///     reusable_function(&mut lens);
     /// }
     ///
     /// # let mut schedule = Schedule::default();
     /// # schedule.add_systems((system_1, system_2));
     /// # schedule.run(&mut world);
     /// ```
+    ///
+    /// ## Allowed Transmutes
+    ///
+    /// Besides removing parameters from the query, you can also
+    /// make limited changes to the types of paramters.
+    ///
+    /// * Can always add/remove `Entity`
+    /// * `Ref<T>` <-> `&T`
+    /// * `&mut T` -> `&T`
+    /// * `&mut T` -> `Ref<T>`
+    /// * [`EntityMut`](crate::world::EntityMut) -> [`EntityRef`](crate::world::EntityRef)
+    ///
     #[track_caller]
     pub fn transmute_fetch<NewQ: WorldQuery>(&mut self) -> QueryLens<'_, NewQ> {
         let new_state = self.state.transmute_fetch(self.world.components());
@@ -453,7 +472,7 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> Query<'w, 's, Q, F> {
         }
     }
 
-    /// helper method to get a [`QueryLens`] with the same fetch as the existing query
+    /// Gets a [`QueryLens`] with the same fetch as the existing query.
     pub fn into_query_lens(&mut self) -> QueryLens<'_, Q> {
         self.transmute_fetch()
     }
@@ -1578,7 +1597,7 @@ impl<'w, 's, Q: ReadOnlyWorldQuery, F: ReadOnlyWorldQuery> Query<'w, 's, Q, F> {
     }
 }
 
-/// A type used to store the generalized query's state.
+/// A type used to store the new [`QueryState`] from [`Query::transmute_fetch`].
 pub struct QueryLens<'world, NewQ: WorldQuery> {
     world: UnsafeWorldCell<'world>,
     state: QueryState<NewQ, ()>,