Skip to content

Commit

Permalink
Ref-style link revision
Browse files Browse the repository at this point in the history 
Moved all links to the bottom of the doc comment.
Links have been alphabetically ordered.

Rebase notes:

- After bevyengine#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.
  • Loading branch information
@Nilirad
Nilirad committed Aug 8, 2022
1 parent be21bbd commit 90a3b16
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 63 deletions.
34 changes: 22 additions & 12 deletions crates/bevy_ecs/src/query/fetch.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -280,15 +273,32 @@ use std::{cell::UnsafeCell, marker::PhantomData};
/// }
/// # bevy_ecs::system::assert_is_system(my_system);
/// ```
///
/// # Safety
///
/// component access of `ROQueryFetch<Self>` must be a subset of `QueryFetch<Self>`
/// Component access of `ROQueryFetch<Self>` must be a subset of `QueryFetch<Self>`
/// and `ROQueryFetch<Self>` must match exactly the same archetypes/tables as `QueryFetch<Self>`
///
/// 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<State = Self::State>;
Expand Down
15 changes: 8 additions & 7 deletions crates/bevy_ecs/src/query/iter.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down Expand Up @@ -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,
Expand Down
84 changes: 40 additions & 44 deletions crates/bevy_ecs/src/system/query.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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]),<br>[`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]),<br>[`get_many`]\([`_mut`][get_many_mut])|Returns the query items for the specified entities.|
/// |[`single`]\([`_mut`][single_mut]),<br>[`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`]),<br>[`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`]),<br>[`get_many`]\([`_mut`][`get_many_mut`])|Returns the query items for the specified entities.|
/// |[`single`]\([`_mut`][`single_mut`]),<br>[`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.
Expand Down Expand Up @@ -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]),<br>[`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(<sub>n</sub>C<sub>r</sub>)|
/// |[`get`]\([`_mut`][get_mut])|O(1)|
/// |([`get_`][get_many])[`many`]|O(k)|
/// |([`get_`][get_many_mut])[`many_mut`]|O(k<sup>2</sup>)|
/// |[`single`]\([`_mut`][single_mut]),<br>[`get_single`]\([`_mut`][get_single_mut])|O(a)|
/// |[`iter`]\([`_mut`][`iter_mut`])|O(n)|
/// |[`for_each`]\([`_mut`][`for_each_mut`]),<br>[`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(<sub>n</sub>C<sub>r</sub>)|
/// |[`get`]\([`_mut`][`get_mut`])|O(1)|
/// |([`get_`][`get_many`])[`many`]|O(k)|
/// |([`get_`][`get_many_mut`])[`many_mut`]|O(k<sup>2</sup>)|
/// |[`single`]\([`_mut`][`single_mut`]),<br>[`get_single`]\([`_mut`][`get_single_mut`])|O(a)|
/// |Archetype based filtering ([`With`], [`Without`], [`Or`])|O(a)|
/// |Change detection filtering ([`Added`], [`Changed`])|O(a + n)|
///
Expand All @@ -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<Q, F>,
Expand Down

0 comments on commit 90a3b16

Please sign in to comment.