Rollup merge of #132019 - daboross:document-partialeq-oncelock, r=Mark-Simulacrum

Document `PartialEq` impl for `OnceLock`

Adds documentation to `std::sync::OnceLock`'s `PartialEq` implementation: specifies publicly that `OnceLock`s are compared based on their contents, and nothing else.

Created in response to, but not directly related to, https://github.com/rust-lang/rust/issues/131959.

## ne

This doesn't create and document `PartialEq::ne`. There's precedent for this in [`RefCell`](https://doc.rust-lang.org/std/cell/struct.RefCell.html#impl-PartialEq-for-RefCell%3CT%3E).

1 files changed, 20 insertions, 0 deletions

diff --git a/library/std/src/sync/once_lock.rs b/library/std/src/sync/once_lock.rs
index be615a5a8ef..0ae3cf4df36 100644
--- a/library/std/src/sync/once_lock.rs
+++ b/library/std/src/sync/once_lock.rs
@@ -634,6 +634,26 @@ impl<T> From<T> for OnceLock<T> {
 
 #[stable(feature = "once_cell", since = "1.70.0")]
 impl<T: PartialEq> PartialEq for OnceLock<T> {
+    /// Equality for two `OnceLock`s.
+    ///
+    /// Two `OnceLock`s are equal if they either both contain values and their
+    /// values are equal, or if neither contains a value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::sync::OnceLock;
+    ///
+    /// let five = OnceLock::new();
+    /// five.set(5).unwrap();
+    ///
+    /// let also_five = OnceLock::new();
+    /// also_five.set(5).unwrap();
+    ///
+    /// assert!(five == also_five);
+    ///
+    /// assert!(OnceLock::<u32>::new() == OnceLock::<u32>::new());
+    /// ```
     #[inline]
     fn eq(&self, other: &OnceLock<T>) -> bool {
         self.get() == other.get()