filtered access docs

crates/bevy_ecs/src/query/access.rs

@@ -148,6 +148,23 @@ impl<T: SparseSetIndex> Access<T> {
 /// An [`Access`] that has been filtered to include and exclude certain combinations of elements.
 ///
 /// Used internally to statically check if queries are disjoint.
+///
+/// Subtle: a `read` or `write` in `access` should not be considered to imply a
+/// `with` access.
+///
+/// For example consider `Query<Option<&T>>` this only has a `read` of `T` as doing
+/// otherwise would allow for queriess to be considered disjoint that actually arent:
+/// - `Query<(&mut T, Option<&U>)>` read/write `T`, read `U`, with `U`
+/// - `Query<&mut T, Without<U>>` read/write `T`, without `U`
+/// from this we could reasonably conclude that the queries are disjoint but they aren't.
+///
+/// In order to solve this the actual access that `Query<(&mut T, Option<&U>)>` has
+/// is read/write `T`, read `U`. It must still have a read `U` access otherwise the following
+/// queries would be incorrectly considered disjoint:
+/// - `Query<&mut T>`  read/write `T`
+/// - `Query<Option<&T>` accesses nothing
+///
+/// See comments the `WorldQuery` impls of `AnyOf`/`Option`/`Or` for more information.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct FilteredAccess<T: SparseSetIndex> {
     access: Access<T>,