diff --git a/crates/bevy_utils/src/futures.rs b/crates/bevy_utils/src/futures.rs index 1b752a33c70ff..6e185144021f4 100644 --- a/crates/bevy_utils/src/futures.rs +++ b/crates/bevy_utils/src/futures.rs @@ -1,14 +1,21 @@ +//! Utilities for working with [`Future`]s. +//! +//! [`Future`]: std::future::Future use std::{ future::Future, pin::Pin, task::{Context, Poll, RawWaker, RawWakerVTable, Waker}, }; +/// Consumes the future, polls it once, and immediately returns the output +/// or returns `None` if it wasn't ready yet. +/// +/// This will cancel the future if it's not ready. pub fn now_or_never(mut future: F) -> Option { let noop_waker = noop_waker(); let mut cx = Context::from_waker(&noop_waker); - // Safety: `future` is not moved and the original value is shadowed + // SAFETY: `future` is not moved and the original value is shadowed let future = unsafe { Pin::new_unchecked(&mut future) }; match future.poll(&mut cx) { diff --git a/crates/bevy_utils/src/label.rs b/crates/bevy_utils/src/label.rs index 835656569c1fe..6c504b0283a30 100644 --- a/crates/bevy_utils/src/label.rs +++ b/crates/bevy_utils/src/label.rs @@ -5,9 +5,16 @@ use std::{ hash::{Hash, Hasher}, }; +/// An object safe version of [`Eq`]. This trait is automatically implemented +/// for any `'static` type that implements `Eq`. pub trait DynEq: Any { + /// Casts the type to `dyn Any`. fn as_any(&self) -> &dyn Any; + /// This method tests for `self` and `other` values to be equal. + /// + /// Implementers should avoid returning `true` when the underlying types are + /// not the same. fn dyn_eq(&self, other: &dyn DynEq) -> bool; } @@ -27,9 +34,15 @@ where } } +/// An object safe version of [`Hash`]. This trait is automatically implemented +/// for any `'static` type that implements `Hash`. pub trait DynHash: DynEq { + /// Casts the type to `dyn Any`. fn as_dyn_eq(&self) -> &dyn DynEq; + /// Feeds this value into the given [`Hasher`]. + /// + /// [`Hash`]: std::hash::Hasher fn dyn_hash(&self, state: &mut dyn Hasher); } diff --git a/crates/bevy_utils/src/lib.rs b/crates/bevy_utils/src/lib.rs index d942ad4feda4d..840c1fdf927f3 100644 --- a/crates/bevy_utils/src/lib.rs +++ b/crates/bevy_utils/src/lib.rs @@ -1,3 +1,11 @@ +//! General utilities for first-party [Bevy] engine crates. +//! +//! [Bevy]: https://bevyengine.org/ + +#![warn(missing_docs)] +#![warn(clippy::undocumented_unsafe_blocks)] + +#[allow(missing_docs)] pub mod prelude { pub use crate::default; } @@ -30,12 +38,14 @@ use std::{ pin::Pin, }; +/// An owned and dynamically typed Future used when you can’t statically type your result or need to add some indirection. #[cfg(not(target_arch = "wasm32"))] pub type BoxedFuture<'a, T> = Pin + Send + 'a>>; #[cfg(target_arch = "wasm32")] pub type BoxedFuture<'a, T> = Pin + 'a>>; +/// A shortcut alias for [`hashbrown::hash_map::Entry`]. pub type Entry<'a, K, V> = hashbrown::hash_map::Entry<'a, K, V, RandomState>; /// A hasher builder that will create a fixed hasher. @@ -174,6 +184,8 @@ impl BuildHasher for PassHash { } } +/// A no-op hash that only works on `u64`s. Will panic if attempting to +/// hash a type containing non-u64 fields. #[derive(Debug, Default)] pub struct PassHasher { hash: u64, diff --git a/crates/bevy_utils/src/synccell.rs b/crates/bevy_utils/src/synccell.rs index 838915fe2500a..4902cd03c3eb8 100644 --- a/crates/bevy_utils/src/synccell.rs +++ b/crates/bevy_utils/src/synccell.rs @@ -1,3 +1,7 @@ +//! A reimplementation of the currently unstable [`std::sync::Exclusive`] +//! +//! [`std::sync::Exclusive`]: https://doc.rust-lang.org/nightly/std/sync/struct.Exclusive.html + /// See [`Exclusive`](https://github.com/rust-lang/rust/issues/98407) for stdlib's upcoming implementation, /// which should replace this one entirely. ///