Document remaining members of bevy_utils (#6897)

# Objective
Partially address #3492. 

## Solution
Document the remaining undocumented members of `bevy_utils` and set `warn(missing_docs)` on the crate level. Also enabled `clippy::undocumented_unsafe_blocks` as a warning on the crate to keep it in sync with `bevy_ecs`'s warnings.

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