[Merged by Bors] - Document remaining members of bevy_utils

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<F: Future>(mut future: F) -> Option<F::Output> {
     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) {

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);
 }
 

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<Box<dyn Future<Output = T> + Send + 'a>>;
 
 #[cfg(target_arch = "wasm32")]
 pub type BoxedFuture<'a, T> = Pin<Box<dyn Future<Output = T> + '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,

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.
 ///