From 90a3b16ee6563812131122a53d1720885301584d Mon Sep 17 00:00:00 2001 From: Nilirad Date: Sun, 31 Jul 2022 17:37:59 +0200 Subject: [PATCH] Ref-style link revision MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moved all links to the bottom of the doc comment. Links have been alphabetically ordered. Rebase notes: - After #5205 got merged, the “Safety” section of `WorldQuery` has changed. I listed the mentioned methods for a better layout. I also removed the `WorldQuery::` prefix for readability. - I don't have enough knowledge of the previous and current state of `WorldQuery` types, so the documentation may be outdated somewhere. `WorldQuery` needs another review round. --- crates/bevy_ecs/src/query/fetch.rs | 34 +++++++----- crates/bevy_ecs/src/query/iter.rs | 15 +++--- crates/bevy_ecs/src/system/query.rs | 84 ++++++++++++++--------------- 3 files changed, 70 insertions(+), 63 deletions(-) diff --git a/crates/bevy_ecs/src/query/fetch.rs b/crates/bevy_ecs/src/query/fetch.rs index a13a4e56dd52c..f0a4350c543c8 100644 --- a/crates/bevy_ecs/src/query/fetch.rs +++ b/crates/bevy_ecs/src/query/fetch.rs @@ -43,13 +43,6 @@ use std::{cell::UnsafeCell, marker::PhantomData}; /// /// Implementing the trait manually can allow for a fundamentally new type of behaviour. /// -/// [`Query`]: crate::system::Query -/// [`With`]: crate::query::With -/// [`Without`]: crate::query::Without -/// [`Or`]: crate::query::Or -/// [`Added`]: crate::query::Added -/// [`Changed`]: crate::query::Changed -/// /// # Trait derivation /// /// Query design can be easily structured by deriving `WorldQuery` for custom types. @@ -280,15 +273,32 @@ use std::{cell::UnsafeCell, marker::PhantomData}; /// } /// # bevy_ecs::system::assert_is_system(my_system); /// ``` +/// /// # Safety /// -/// component access of `ROQueryFetch` must be a subset of `QueryFetch` +/// Component access of `ROQueryFetch` must be a subset of `QueryFetch` /// and `ROQueryFetch` must match exactly the same archetypes/tables as `QueryFetch` /// -/// Implementor must ensure that [`WorldQuery::update_component_access`] and -/// [`WorldQuery::update_archetype_component_access`] exactly reflects the results of -/// [`WorldQuery::matches_component_set`], [`WorldQuery::archetype_fetch`], and -/// [`WorldQuery::table_fetch`]. +/// Implementor must ensure that +/// [`update_component_access`] and [`update_archetype_component_access`] +/// exactly reflects the results of the following methods: +/// +/// - [`matches_component_set`] +/// - [`archetype_fetch`] +/// - [`table_fetch`] +/// +/// [`archetype_fetch`]: Self::archetype_fetch +/// [`Added`]: crate::query::Added +/// [`Changed`]: crate::query::Changed +/// [`Fetch`]: crate::query::WorldQueryGats::Fetch +/// [`matches_component_set`]: Self::matches_component_set +/// [`Or`]: crate::query::Or +/// [`Query`]: crate::system::Query +/// [`table_fetch`]: Self::table_fetch +/// [`update_archetype_component_access`]: Self::update_archetype_component_access +/// [`update_component_access`]: Self::update_component_access +/// [`With`]: crate::query::With +/// [`Without`]: crate::query::Without pub unsafe trait WorldQuery: for<'w> WorldQueryGats<'w> { /// The read-only variant of this [`WorldQuery`], which satisfies the [`ReadOnlyWorldQuery`] trait. type ReadOnly: ReadOnlyWorldQuery; diff --git a/crates/bevy_ecs/src/query/iter.rs b/crates/bevy_ecs/src/query/iter.rs index 23c48aea62d5f..fd4ac9b7e7baf 100644 --- a/crates/bevy_ecs/src/query/iter.rs +++ b/crates/bevy_ecs/src/query/iter.rs @@ -228,13 +228,7 @@ where /// /// It implements [`Iterator`] only if it iterates over read-only query items ([learn more]). /// -/// In the case of mutable query items, it can be iterated by calling [`fetch_next`](Self::fetch_next) in a `while let` loop. -/// -/// [`Query`]: crate::system::Query -/// [performance section]: crate::system::Query#performance -/// [`Query::iter_combinations`]: crate::system::Query::iter_combinations -/// [`Query::iter_combinations_mut`]: crate::system::Query::iter_combinations_mut -/// [learn more]: Self#impl-Iterator +/// In the case of mutable query items, it can be iterated by calling [`fetch_next`] in a `while let` loop. /// /// # Examples /// @@ -266,6 +260,13 @@ where /// } /// } /// ``` +/// +/// [`fetch_next`]: Self::fetch_next +/// [learn more]: Self#impl-Iterator +/// [performance section]: crate::system::Query#performance +/// [`Query`]: crate::system::Query +/// [`Query::iter_combinations`]: crate::system::Query::iter_combinations +/// [`Query::iter_combinations_mut`]: crate::system::Query::iter_combinations_mut pub struct QueryCombinationIter<'w, 's, Q: WorldQuery, F: WorldQuery, const K: usize> { tables: &'w Tables, archetypes: &'w Archetypes, diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index d28178d5dbd9c..ffbd9d7c30dde 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -24,10 +24,6 @@ use std::{any::TypeId, borrow::Borrow, fmt::Debug}; /// A set of conditions that determines wheter query items should be kept or discarded. /// This type parameter is optional. /// -/// [System parameter]: crate::system::SystemParam -/// [entity identifiers]: crate::entity::Entity -/// [components]: crate::component::Component -/// /// # System parameter declaration /// /// A query should always be declared as a system parameter. @@ -131,9 +127,6 @@ use std::{any::TypeId, borrow::Borrow, fmt::Debug}; /// /// See the [performance] section to learn more about the impact of optional components. /// -/// [`AnyOf`]: crate::query::AnyOf -/// [performance]: #performance -/// /// ## Disjoint queries /// /// A system cannot contain two queries that break Rust's mutability rules. @@ -194,13 +187,13 @@ use std::{any::TypeId, borrow::Borrow, fmt::Debug}; /// /// |Query methods|Effect| /// |:---:|---| -/// |[`iter`]\([`_mut`][iter_mut])|Returns an iterator over all query items.| -/// |[`for_each`]\([`_mut`][for_each_mut]),
[`par_for_each`]\([`_mut`][par_for_each_mut])|Runs a specified function for each query item.| -/// |[`iter_many`]\([`_mut`][iter_many_mut])|Iterates or runs a specified function over query items generated by a list of entities.| -/// |[`iter_combinations`]\([`_mut`][iter_combinations_mut])|Returns an iterator over all combinations of a specified number of query items.| -/// |[`get`]\([`_mut`][get_mut])|Returns the query item for the specified entity.| -/// |[`many`]\([`_mut`][many_mut]),
[`get_many`]\([`_mut`][get_many_mut])|Returns the query items for the specified entities.| -/// |[`single`]\([`_mut`][single_mut]),
[`get_single`]\([`_mut`][get_single_mut])|Returns the query item while veryfing that there aren't others.| +/// |[`iter`]\([`_mut`][`iter_mut`])|Returns an iterator over all query items.| +/// |[`for_each`]\([`_mut`][`for_each_mut`]),
[`par_for_each`]\([`_mut`][`par_for_each_mut`])|Runs a specified function for each query item.| +/// |[`iter_many`]\([`_mut`][`iter_many_mut`])|Iterates or runs a specified function over query items generated by a list of entities.| +/// |[`iter_combinations`]\([`_mut`][`iter_combinations_mut`])|Returns an iterator over all combinations of a specified number of query items.| +/// |[`get`]\([`_mut`][`get_mut`])|Returns the query item for the specified entity.| +/// |[`many`]\([`_mut`][`many_mut`]),
[`get_many`]\([`_mut`][`get_many_mut`])|Returns the query items for the specified entities.| +/// |[`single`]\([`_mut`][`single_mut`]),
[`get_single`]\([`_mut`][`get_single_mut`])|Returns the query item while veryfing that there aren't others.| /// /// There are two methods for each type of query operation: immutable and mutable (ending with `_mut`). /// When using immutable methods, the query items returned are of type [`ROQueryItem`], a read-only version of the query item. @@ -230,14 +223,14 @@ use std::{any::TypeId, borrow::Borrow, fmt::Debug}; /// /// |Query operation|Computational complexity| /// |:---:|:---:| -/// |[`iter`]\([`_mut`][iter_mut])|O(n)| -/// |[`for_each`]\([`_mut`][for_each_mut]),
[`par_for_each`]\([`_mut`][par_for_each_mut])|O(n)| -/// |[`iter_many`]\([`_mut`][iter_many_mut])|O(k)| -/// |[`iter_combinations`]\([`_mut`][iter_combinations_mut])|O(nCr)| -/// |[`get`]\([`_mut`][get_mut])|O(1)| -/// |([`get_`][get_many])[`many`]|O(k)| -/// |([`get_`][get_many_mut])[`many_mut`]|O(k2)| -/// |[`single`]\([`_mut`][single_mut]),
[`get_single`]\([`_mut`][get_single_mut])|O(a)| +/// |[`iter`]\([`_mut`][`iter_mut`])|O(n)| +/// |[`for_each`]\([`_mut`][`for_each_mut`]),
[`par_for_each`]\([`_mut`][`par_for_each_mut`])|O(n)| +/// |[`iter_many`]\([`_mut`][`iter_many_mut`])|O(k)| +/// |[`iter_combinations`]\([`_mut`][`iter_combinations_mut`])|O(nCr)| +/// |[`get`]\([`_mut`][`get_mut`])|O(1)| +/// |([`get_`][`get_many`])[`many`]|O(k)| +/// |([`get_`][`get_many_mut`])[`many_mut`]|O(k2)| +/// |[`single`]\([`_mut`][`single_mut`]),
[`get_single`]\([`_mut`][`get_single_mut`])|O(a)| /// |Archetype based filtering ([`With`], [`Without`], [`Or`])|O(a)| /// |Change detection filtering ([`Added`], [`Changed`])|O(a + n)| /// @@ -247,36 +240,39 @@ use std::{any::TypeId, borrow::Borrow, fmt::Debug}; /// It is strongly advised to only use `for_each` if it tangibly improves performance: /// be sure profile or benchmark both before and after the change. /// +/// [`Added`]: crate::query::Added +/// [`AnyOf`]: crate::query::AnyOf /// [binomial coefficient]: https://en.wikipedia.org/wiki/Binomial_coefficient -/// [`iter`]: Self::iter +/// [`Changed`]: crate::query::Changed +/// [components]: crate::component::Component +/// [entity identifiers]: crate::entity::Entity /// [`for_each`]: Self::for_each -/// [`par_for_each`]: Self::par_for_each -/// [`iter_combinations`]: Self::iter_combinations +/// [`for_each_mut`]: Self::for_each_mut /// [`get`]: Self::get +/// [`get_many`]: Self::get_many +/// [`get_many_mut`]: Self::get_many_mut +/// [`get_mut`]: Self::get_mut +/// [`get_single`]: Self::get_single +/// [`get_single_mut`]: Self::get_single_mut +/// [`iter`]: Self::iter +/// [`iter_combinations`]: Self::iter_combinations +/// [`iter_combinations_mut`]: Self::iter_combinations_mut +/// [`iter_many`]: Self::iter_many +/// [`iter_many_mut`]: Self::iter_many_mut +/// [`iter_mut`]: Self::iter_mut /// [`many`]: Self::many /// [`many_mut`]: Self::many_mut +/// [`Or`]: crate::query::Or +/// [`par_for_each`]: Self::par_for_each +/// [`par_for_each_mut`]: Self::par_for_each_mut +/// [performance]: #performance /// [`single`]: Self::single -/// [`get_single`]: Self::get_single -/// [iter_mut]: Self::iter_mut -/// [for_each_mut]: Self::for_each_mut -/// [par_for_each_mut]: Self::par_for_each_mut -/// [iter_combinations_mut]: Self::iter_combinations_mut -/// [get_mut]: Self::get_mut -/// [get_many]: Self::get_many -/// [get_many_mut]: Self::get_many_mut -/// [single_mut]: Self::single_mut -/// [get_single_mut]: Self::get_single_mut +/// [`single_mut`]: Self::single_mut +/// [`SparseSet`]: crate::storage::SparseSet +/// [System parameter]: crate::system::SystemParam +/// [`Table`]: crate::storage::Table /// [`With`]: crate::query::With /// [`Without`]: crate::query::Without -/// [`Or`]: crate::query::Or -/// [`Added`]: crate::query::Added -/// [`Changed`]: crate::query::Changed -/// [many_mut]: Self::many_mut -/// [`get_many`]: Self::get_many -/// [`iter_many`]: Self::iter_many -/// [iter_many_mut]: Self::iter_many_mut -/// [`Table`]: crate::storage::Table -/// [`SparseSet`]: crate::storage::SparseSet pub struct Query<'world, 'state, Q: WorldQuery, F: WorldQuery = ()> { pub(crate) world: &'world World, pub(crate) state: &'state QueryState,