From d070535063cbe432400426919c0bea41e22c6e50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Sat, 27 May 2023 06:36:44 +0100 Subject: [PATCH 1/8] Document query errors --- crates/bevy_ecs/src/query/state.rs | 13 +++++-- crates/bevy_ecs/src/system/query.rs | 53 +++++++++++++++++++++++++++-- 2 files changed, 61 insertions(+), 5 deletions(-) diff --git a/crates/bevy_ecs/src/query/state.rs b/crates/bevy_ecs/src/query/state.rs index 49b4d7202420e..6191f76ba39f3 100644 --- a/crates/bevy_ecs/src/query/state.rs +++ b/crates/bevy_ecs/src/query/state.rs @@ -1162,12 +1162,19 @@ impl QueryState { } } -/// An error that occurs when retrieving a specific [`Entity`]'s query result. +/// An error that occurs when retrieving a specific [`Entity`]'s query result from [`QueryState`]. // TODO: return the type_name as part of this error #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub enum QueryEntityError { + /// The given [`Entity`]'s components do not match the query. + /// + /// Either it does not have a requested component, or it has a component which the query filters out. QueryDoesNotMatch(Entity), + /// The given [`Entity`] does not exist. NoSuchEntity(Entity), + /// The [`Entity`] was requested mutably more than once. + /// + /// See [`QueryState::get_many_mut`] for an example. AliasedMutability(Entity), } @@ -1177,7 +1184,7 @@ impl fmt::Display for QueryEntityError { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { match self { QueryEntityError::QueryDoesNotMatch(_) => { - write!(f, "The given entity does not have the requested component.") + write!(f, "The given entity's components do not match the query.") } QueryEntityError::NoSuchEntity(_) => write!(f, "The requested entity does not exist."), QueryEntityError::AliasedMutability(_) => { @@ -1300,7 +1307,9 @@ mod tests { /// [`QueryState::single`] or [`QueryState::single_mut`]. #[derive(Debug)] pub enum QuerySingleError { + /// No entities fit the query. NoEntities(&'static str), + /// Multiple entities fit the query. MultipleEntities(&'static str), } diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index 4316389adecc1..9ff8b2c260747 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -1054,7 +1054,7 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> Query<'w, 's, Q, F> { /// Returns a mutable reference to the component `T` of the given entity. /// - /// In case of a nonexisting entity or mismatched component, a [`QueryEntityError`] is returned instead. + /// In case of a nonexisting entity or mismatched component, a [`QueryComponentError`] is returned instead. /// /// # Example /// @@ -1090,7 +1090,7 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> Query<'w, 's, Q, F> { /// Returns a mutable reference to the component `T` of the given entity. /// - /// In case of a nonexisting entity or mismatched component, a [`QueryEntityError`] is returned instead. + /// In case of a nonexisting entity or mismatched component, a [`QueryComponentError`] is returned instead. /// /// # Safety /// @@ -1357,12 +1357,59 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> IntoIterator for &'w mut Quer } } -/// An error that occurs when retrieving a specific [`Entity`]'s component from a [`Query`] +/// An error that occurs when retrieving a specific [`Entity`]'s component from a [`Query`]. #[derive(Debug, PartialEq, Eq)] pub enum QueryComponentError { + /// The [`Query`] does not have read access to the requested component. + /// + /// # Example + /// + /// ``` + /// # use bevy_ecs::{prelude::*, system::QueryComponentError}; + /// # + /// # #[derive(Component)] + /// # struct OtherComponent; + /// # + /// # #[derive(Component)] + /// # struct RequestedComponent; + /// # + /// # #[derive(Resource)] + /// # struct SpecificEntity { + /// # entity: Entity, + /// # } + /// # + /// fn get_missing_read_access_error(query: Query<&OtherComponent>, res: Res) { + /// if let Err(QueryComponentError::MissingReadAccess) = query.get_component::(res.entity) { + /// println!("query doesn't have read access to RequestedComponent"); + /// } + /// } + /// # bevy_ecs::system::assert_is_system(get_missing_read_access_error); MissingReadAccess, + /// The [`Query`] does not have write access to the requested component. + /// + /// # Example + /// + /// ``` + /// # use bevy_ecs::{prelude::*, system::QueryComponentError}; + /// # + /// # #[derive(Component)] + /// # struct RequestedComponent; + /// # + /// # #[derive(Resource)] + /// # struct SpecificEntity { + /// # entity: Entity, + /// # } + /// # + /// fn get_missing_write_access_error(mut query: Query<&RequestedComponent>, res: Res) { + /// if let Err(QueryComponentError::MissingWriteAccess) = query.get_component_mut::(res.entity) { + /// println!("query doesn't have write access to RequestedComponent"); + /// } + /// } + /// # bevy_ecs::system::assert_is_system(get_missing_read_access_error); MissingWriteAccess, + /// The given [`Entity`] does not have the requested component. MissingComponent, + /// The requested [`Entity`] does not exist. NoSuchEntity, } From 25e18781d317e8ebbc1d32cbb30aa075d5b4ac9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= <134181069+Selene-Amanita@users.noreply.github.com> Date: Sat, 27 May 2023 16:38:08 +0100 Subject: [PATCH 2/8] Document query errors suggested change #1 Co-authored-by: harudagondi --- crates/bevy_ecs/src/query/state.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_ecs/src/query/state.rs b/crates/bevy_ecs/src/query/state.rs index 6191f76ba39f3..60e4a8b889ada 100644 --- a/crates/bevy_ecs/src/query/state.rs +++ b/crates/bevy_ecs/src/query/state.rs @@ -1307,7 +1307,7 @@ mod tests { /// [`QueryState::single`] or [`QueryState::single_mut`]. #[derive(Debug)] pub enum QuerySingleError { - /// No entities fit the query. + /// No entity fits the query. NoEntities(&'static str), /// Multiple entities fit the query. MultipleEntities(&'static str), From dd0ca47b2ae69ffea9a2b03e4bbdff2a10bf7767 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= <134181069+Selene-Amanita@users.noreply.github.com> Date: Sat, 27 May 2023 16:38:33 +0100 Subject: [PATCH 3/8] Document query errors suggested change #2 Co-authored-by: harudagondi --- crates/bevy_ecs/src/system/query.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index 9ff8b2c260747..1a48e2aa063d0 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -1362,6 +1362,8 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> IntoIterator for &'w mut Quer pub enum QueryComponentError { /// The [`Query`] does not have read access to the requested component. /// + /// This error occurs when the requested component is not included in the original query. + /// /// # Example /// /// ``` From 28c9b52a13a073cf8cbabe5b755fd90e3a28a6d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= <134181069+Selene-Amanita@users.noreply.github.com> Date: Sat, 27 May 2023 16:38:47 +0100 Subject: [PATCH 4/8] Document query errors suggested change #3 Co-authored-by: harudagondi --- crates/bevy_ecs/src/system/query.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index 1a48e2aa063d0..c31d247c31192 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -1389,6 +1389,8 @@ pub enum QueryComponentError { MissingReadAccess, /// The [`Query`] does not have write access to the requested component. /// + /// This error occurs when the requested component is not included in the original query, or the mutability of the requested component is mismatched with the original query. + /// /// # Example /// /// ``` From d5642bf0756f5c6c40913d86732c4b7e606837a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Sat, 27 May 2023 22:43:43 +0100 Subject: [PATCH 5/8] Formating with rustfmt --- crates/bevy_ecs/src/query/state.rs | 4 ++-- crates/bevy_ecs/src/system/query.rs | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/bevy_ecs/src/query/state.rs b/crates/bevy_ecs/src/query/state.rs index 60e4a8b889ada..a63681adfde67 100644 --- a/crates/bevy_ecs/src/query/state.rs +++ b/crates/bevy_ecs/src/query/state.rs @@ -1167,13 +1167,13 @@ impl QueryState { #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub enum QueryEntityError { /// The given [`Entity`]'s components do not match the query. - /// + /// /// Either it does not have a requested component, or it has a component which the query filters out. QueryDoesNotMatch(Entity), /// The given [`Entity`] does not exist. NoSuchEntity(Entity), /// The [`Entity`] was requested mutably more than once. - /// + /// /// See [`QueryState::get_many_mut`] for an example. AliasedMutability(Entity), } diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index c31d247c31192..db78e7658795c 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -1361,7 +1361,7 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> IntoIterator for &'w mut Quer #[derive(Debug, PartialEq, Eq)] pub enum QueryComponentError { /// The [`Query`] does not have read access to the requested component. - /// + /// /// This error occurs when the requested component is not included in the original query. /// /// # Example @@ -1388,7 +1388,7 @@ pub enum QueryComponentError { /// # bevy_ecs::system::assert_is_system(get_missing_read_access_error); MissingReadAccess, /// The [`Query`] does not have write access to the requested component. - /// + /// /// This error occurs when the requested component is not included in the original query, or the mutability of the requested component is mismatched with the original query. /// /// # Example From 16d460a8713a240b7ca3d49d52c0c62bb3248a61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Sun, 28 May 2023 11:22:27 +0100 Subject: [PATCH 6/8] Document query errors suggested changes 4 --- crates/bevy_ecs/src/query/state.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/bevy_ecs/src/query/state.rs b/crates/bevy_ecs/src/query/state.rs index a63681adfde67..b5ccf8263e233 100644 --- a/crates/bevy_ecs/src/query/state.rs +++ b/crates/bevy_ecs/src/query/state.rs @@ -1162,7 +1162,7 @@ impl QueryState { } } -/// An error that occurs when retrieving a specific [`Entity`]'s query result from [`QueryState`]. +/// An error that occurs when retrieving a specific [`Entity`]'s query result from [`Query`](crate::system::Query) or [`QueryState`]. // TODO: return the type_name as part of this error #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub enum QueryEntityError { @@ -1303,8 +1303,8 @@ mod tests { } } -/// An error that occurs when evaluating a [`QueryState`] as a single expected resulted via -/// [`QueryState::single`] or [`QueryState::single_mut`]. +/// An error that occurs when evaluating a [`Query`](crate::system::Query) or [`QueryState`] as a single expected result via +/// [`get_single`](crate::system::Query::get_single) or [`get_single_mut`](crate::system::Query::get_single_mut). #[derive(Debug)] pub enum QuerySingleError { /// No entity fits the query. From 0d7972dd84235bef7c83b8d1dff1b3bfb735a072 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Mon, 29 May 2023 18:22:52 +0100 Subject: [PATCH 7/8] Document Query Error fix check-doc --- crates/bevy_ecs/src/system/query.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index db78e7658795c..d112c90ab9e8c 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -1386,6 +1386,7 @@ pub enum QueryComponentError { /// } /// } /// # bevy_ecs::system::assert_is_system(get_missing_read_access_error); + /// ``` MissingReadAccess, /// The [`Query`] does not have write access to the requested component. /// @@ -1409,7 +1410,8 @@ pub enum QueryComponentError { /// println!("query doesn't have write access to RequestedComponent"); /// } /// } - /// # bevy_ecs::system::assert_is_system(get_missing_read_access_error); + /// # bevy_ecs::system::assert_is_system(get_missing_write_access_error); + /// ``` MissingWriteAccess, /// The given [`Entity`] does not have the requested component. MissingComponent, From 5559ce773a2646dfc22f2f995e91ebe3fda636d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9l=C3=A8ne=20Amanita?= Date: Mon, 29 May 2023 21:35:30 +0100 Subject: [PATCH 8/8] Document query errors - assert correct errors in tests --- crates/bevy_ecs/src/system/query.rs | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index d112c90ab9e8c..1e18705dcede0 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -1372,7 +1372,7 @@ pub enum QueryComponentError { /// # #[derive(Component)] /// # struct OtherComponent; /// # - /// # #[derive(Component)] + /// # #[derive(Component, PartialEq, Debug)] /// # struct RequestedComponent; /// # /// # #[derive(Resource)] @@ -1381,9 +1381,11 @@ pub enum QueryComponentError { /// # } /// # /// fn get_missing_read_access_error(query: Query<&OtherComponent>, res: Res) { - /// if let Err(QueryComponentError::MissingReadAccess) = query.get_component::(res.entity) { - /// println!("query doesn't have read access to RequestedComponent"); - /// } + /// assert_eq!( + /// query.get_component::(res.entity), + /// Err(QueryComponentError::MissingReadAccess), + /// ); + /// println!("query doesn't have read access to RequestedComponent because it does not appear in Query<&OtherComponent>"); /// } /// # bevy_ecs::system::assert_is_system(get_missing_read_access_error); /// ``` @@ -1397,7 +1399,7 @@ pub enum QueryComponentError { /// ``` /// # use bevy_ecs::{prelude::*, system::QueryComponentError}; /// # - /// # #[derive(Component)] + /// # #[derive(Component, PartialEq, Debug)] /// # struct RequestedComponent; /// # /// # #[derive(Resource)] @@ -1406,9 +1408,11 @@ pub enum QueryComponentError { /// # } /// # /// fn get_missing_write_access_error(mut query: Query<&RequestedComponent>, res: Res) { - /// if let Err(QueryComponentError::MissingWriteAccess) = query.get_component_mut::(res.entity) { - /// println!("query doesn't have write access to RequestedComponent"); - /// } + /// assert_eq!( + /// query.get_component::(res.entity), + /// Err(QueryComponentError::MissingWriteAccess), + /// ); + /// println!("query doesn't have write access to RequestedComponent because it doesn't have &mut in Query<&RequestedComponent>"); /// } /// # bevy_ecs::system::assert_is_system(get_missing_write_access_error); /// ```