From ebbd961739403ced7a05aa7729b746646dd78847 Mon Sep 17 00:00:00 2001
From: Younes <3153107+younes-io@users.noreply.github.com>
Date: Mon, 20 Jan 2025 22:31:20 +0100
Subject: [PATCH] docs: enhance documentation in `query.rs` to clarify
 borrowing rules (#17370)

docs: enhance documentation in `query.rs` to clarify borrowing rules.

Please, let me know if you don't agree with the wording.. There is
always room for improvement.

Tested locally and it looks like this:


![image](https://github.com/user-attachments/assets/1283fcac-c5f7-426f-844f-fc2a12ce2b42)

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
---
 crates/bevy_ecs/src/system/query.rs | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs
index 1680eea8497cd..1db5b22ef5dfe 100644
--- a/crates/bevy_ecs/src/system/query.rs
+++ b/crates/bevy_ecs/src/system/query.rs
@@ -227,6 +227,11 @@ use core::{
 /// # struct ComponentA;
 /// # fn system(
 /// // This will panic!
+/// // EntityRef provides read access to ALL components on an entity.
+/// // When combined with &mut ComponentA in the same query, it creates
+/// // a conflict because EntityRef could read ComponentA while the &mut
+/// // attempts to modify it - violating Rust's borrowing rules of no
+/// // simultaneous read+write access.
 /// query: Query<(EntityRef, &mut ComponentA)>
 /// # ) {}
 /// # bevy_ecs::system::assert_system_does_not_conflict(system);
@@ -239,11 +244,18 @@ use core::{
 /// # struct ComponentB;
 /// # fn system(
 /// // This will not panic.
+/// // This creates a perfect separation where:
+/// // 1. First query reads entities that have ComponentA
+/// // 2. Second query modifies ComponentB only on entities that DON'T have ComponentA
+/// // Result: No entity can ever be accessed by both queries simultaneously
 /// query_a: Query<EntityRef, With<ComponentA>>,
 /// query_b: Query<&mut ComponentB, Without<ComponentA>>,
 /// # ) {}
 /// # bevy_ecs::system::assert_system_does_not_conflict(system);
 /// ```
+/// The fundamental rule: [`EntityRef`]'s ability to read all components means it can never
+/// coexist with mutable access. With/Without filters guarantee this by keeping the
+/// queries on completely separate entities.
 ///
 /// # Accessing query items
 ///