Apply documentation suggestions

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Author: vladbat00

crates/bevy_ecs/macros/src/fetch.rs

@@ -374,7 +374,7 @@ pub fn derive_filter_fetch_impl(input: TokenStream) -> TokenStream {
             type ReadOnlyFetch = #fetch_struct_name #ty_generics;
         }
 
-        /// SAFETY: each item in the struct is read only
+        /// SAFETY: each item in the struct is read-only as filters never actually fetch any data that could be mutated
         unsafe impl #impl_generics #path::query::ReadOnlyFetch for #fetch_struct_name #ty_generics #where_clause {}
     });
     tokens

crates/bevy_ecs/src/query/fetch.rs

@@ -145,48 +145,90 @@ pub type QueryItem<'w, 's, Q> = <<Q as WorldQuery>::Fetch as Fetch<'w, 's>>::Ite
 ///     optional_foo: Option<&'w OptionalFoo>,
 /// }
 ///
+/// // You can also compose derived queries with regular ones in tuples.
+/// fn my_system(query: Query<(&Foo, MyQuery, FooQuery)>) {
+///     for (foo, my_query, foo_query) in query.iter() {
+///         foo; my_query; foo_query;
+///     }
+/// }
+///
+/// # my_system.system();
 /// ```
 ///
 /// ## Read-only queries
 ///
 /// All queries that are derived with `Fetch` macro have their read-only variants with `ReadOnly`
-/// suffix. If you are going to use a query only for reading, you can mark it with `read_only`
-/// attribute.
+/// suffix. If you are going to use a query which can only read data from the ECS, you can mark it
+/// with the `read_only` attribute.
 ///
 /// ```
 /// # use bevy_ecs::prelude::*;
 /// use bevy_ecs::query::{Fetch, ReadOnlyFetch, WorldQuery};
 ///
 /// #[derive(Component)]
-/// struct Foo;
+/// struct A(i32);
 /// #[derive(Component)]
-/// struct Bar;
+/// struct B(i32);
 ///
 /// #[derive(Fetch)]
-/// #[read_only]
-/// struct FooQuery<'w> {
-///     foo: &'w Foo,
-///     bar_query: BarQueryReadOnly<'w>,
+/// struct SumQuery<'w> {
+///     a: &'w A,
+///     b: &'w B,
+/// }
+///
+/// // This implementation is only available when iterating with `iter_mut`.
+/// impl<'w> SumQuery<'w> {
+///     fn calc(&self) -> i32 {
+///         let Self { a: A(a), b: B(b) } = self;
+///         a + b
+///     }
+/// }
+///
+/// // If you want to use it with `iter`, you'll need to write an additional implementation.
+/// impl<'w> SumQueryReadOnly<'w> {
+///     fn calc(&self) -> i32 {
+///         let Self { a: A(a), b: B(b) } = self;
+///         a + b
+///     }
 /// }
 ///
+/// // If you are never going to mutate the data, you can mark the query with the `read_only`
+/// // attribute and write the implementation only once.
 /// #[derive(Fetch)]
-/// struct BarQuery<'w> {
-///     bar: &'w Bar,
+/// #[read_only]
+/// struct ProductQuery<'w> {
+///     a: &'w A,
+///     b: &'w B,
 /// }
 ///
-/// fn assert_read_only<T: ReadOnlyFetch>() {}
+/// impl<'w> ProductQuery<'w> {
+///     fn calc(&self) -> i32 {
+///         let Self { a: A(a), b: B(b) } = self;
+///         a * b
+///     }
+/// }
 ///
-/// assert_read_only::<<FooQuery as WorldQuery>::Fetch>();
-/// assert_read_only::<<BarQuery as WorldQuery>::ReadOnlyFetch>();
-/// // the following will fail to compile:
-/// // assert_read_only::<<BarQuery as WorldQuery>::Fetch>();
+/// fn my_system(mut sum_query: Query<SumQuery>, product_query: Query<ProductQuery>) {
+///     // Iterator's item is `SumQueryReadOnly`.
+///     for sum in sum_query.iter() {
+///         println!("Sum: {}", sum.calc());
+///     }
+///     // Iterator's item is `SumQuery`.
+///     for sum in sum_query.iter_mut() {
+///         println!("Sum (mut): {}", sum.calc());
+///     }
+///     // Iterator's item is `ProductQuery`.
+///     for product in product_query.iter() {
+///         println!("Product: {}", product.calc());
+///     }
+/// }
 /// ```
 ///
 /// If you want to use derive macros with read-only query variants, you need to pass them with
-/// using `read_only_derive` attribute.
-///
-/// # use bevy_ecs::prelude::*;
-/// use bevy_ecs::query::{Fetch, ReadOnlyFetch, WorldQuery};
+/// using the `read_only_derive` attribute. As the `Fetch` macro generates an additional struct
+/// for `ReadOnlyFetch` implementation (granted it isn't marked with the `read_only` attribute),
+/// you may want it to inherit the same derives. Since derive macros can't access information about
+/// other derives, they need to be passed manually with the `read_only_derive` attribute.
 ///
 /// ```
 /// # use bevy_ecs::prelude::*;

examples/ecs/custom_query_param.rs

@@ -14,7 +14,7 @@ use std::{fmt::Debug, marker::PhantomData};
 /// declared as named structs can bring the following advantages:
 /// - They help to avoid destructuring or using `q.0, q.1, ...` access pattern.
 /// - Adding, removing components or changing items order with structs greatly reduces maintenance
-///   burden, as you don't need to update statements that destructure tuples, care abort order
+///   burden, as you don't need to update statements that destructure tuples, care about order
 ///   of elements, etc. Instead, you can just add or remove places where a certain element is used.
 /// - Named structs enable the composition pattern, that makes query types easier to re-use.
 /// - You can bypass the limit of 15 components that exists for query tuples.
@@ -130,7 +130,7 @@ fn print_components_iter(
     println!();
 }
 
-// If you are going to use a query only for reading, you can mark it with `read_only` attribute
+// If you are never going to mutate the data in a query, you can mark it with `read_only` attribute
 // to avoid creating an additional type with `ReadOnly` suffix.
 #[derive(Fetch)]
 #[read_only]