OnceCell & OnceLock docs: Using (un)initialized consistently

library/core/src/cell/once.rs

@@ -10,6 +10,12 @@ use crate::{fmt, mem};
 ///
 /// For a thread-safe version of this struct, see [`std::sync::OnceLock`].
 ///
+/// A OnceCell conceptually has two states, called the `uninitialized state`
+/// and the `initialized state`.
+///
+/// Like an `enum { Uninitialized, Initialized(T) }`,
+/// except that it has invariants to uphold, so the enum is hidden.
+///
 /// [`RefCell`]: crate::cell::RefCell
 /// [`Cell`]: crate::cell::Cell
 /// [`std::sync::OnceLock`]: ../../std/sync/struct.OnceLock.html
@@ -35,7 +41,7 @@ pub struct OnceCell<T> {
 }
 
 impl<T> OnceCell<T> {
-    /// Creates a new empty cell.
+    /// Creates a new cell in the uninitialized state.
     #[inline]
     #[must_use]
     #[stable(feature = "once_cell", since = "1.70.0")]
@@ -46,7 +52,7 @@ impl<T> OnceCell<T> {
 
     /// Gets the reference to the underlying value.
     ///
-    /// Returns `None` if the cell is empty.
+    /// Returns `None` if the cell is in the uninitialized state.
     #[inline]
     #[stable(feature = "once_cell", since = "1.70.0")]
     pub fn get(&self) -> Option<&T> {
@@ -56,19 +62,19 @@ impl<T> OnceCell<T> {
 
     /// Gets the mutable reference to the underlying value.
     ///
-    /// Returns `None` if the cell is empty.
+    /// Returns `None` if the cell is in the uninitialized state.
     #[inline]
     #[stable(feature = "once_cell", since = "1.70.0")]
     pub fn get_mut(&mut self) -> Option<&mut T> {
         self.inner.get_mut().as_mut()
     }
 
-    /// Sets the contents of the cell to `value`.
+    /// Initializes the cell's value to `value`.
     ///
     /// # Errors
     ///
-    /// This method returns `Ok(())` if the cell was empty and `Err(value)` if
-    /// it was full.
+    /// This method returns `Ok(())` if the cell was in the uninitialized state
+    /// and `Err(value)` if it was already in the initialized state.
     ///
     /// # Examples
     ///
@@ -92,13 +98,13 @@ impl<T> OnceCell<T> {
         }
     }
 
-    /// Sets the contents of the cell to `value` if the cell was empty, then
-    /// returns a reference to it.
+    /// Initializes the cell's value to `value` if the cell was in the
+    /// uninitialized state, then returns a reference to it.
     ///
     /// # Errors
     ///
-    /// This method returns `Ok(&value)` if the cell was empty and
-    /// `Err(&current_value, value)` if it was full.
+    /// This method returns `Ok(&value)` if the cell was in the uninitialized state
+    /// and `Err((&current_value, value))` if it was already in the initialized state.
     ///
     /// # Examples
     ///
@@ -130,13 +136,13 @@ impl<T> OnceCell<T> {
         Ok(slot.insert(value))
     }
 
-    /// Gets the contents of the cell, initializing it with `f`
-    /// if the cell was empty.
+    /// Gets the cell's value, initializing it to `f()`
+    /// if the cell was in the uninitialized state.
     ///
     /// # Panics
     ///
-    /// If `f` panics, the panic is propagated to the caller, and the cell
-    /// remains uninitialized.
+    /// If `f()` panics, the panic is propagated to the caller, and the cell
+    /// remains in the uninitialized state.
     ///
     /// It is an error to reentrantly initialize the cell from `f`. Doing
     /// so results in a panic.
@@ -163,13 +169,13 @@ impl<T> OnceCell<T> {
         }
     }
 
-    /// Gets the mutable reference of the contents of the cell,
-    /// initializing it with `f` if the cell was empty.
+    /// Gets the mutable reference of the cell's value,
+    /// initializing it to `f()` if the cell was in the uninitialized state.
     ///
     /// # Panics
     ///
-    /// If `f` panics, the panic is propagated to the caller, and the cell
-    /// remains uninitialized.
+    /// If `f()` panics, the panic is propagated to the caller, and the cell
+    /// remains in the uninitialized state.
     ///
     /// # Examples
     ///
@@ -199,14 +205,14 @@ impl<T> OnceCell<T> {
         }
     }
 
-    /// Gets the contents of the cell, initializing it with `f` if
-    /// the cell was empty. If the cell was empty and `f` failed, an
-    /// error is returned.
+    /// Gets the cell's value, initializing it to `f()` if
+    /// the cell was in the uninitialized state. If the cell was in
+    /// the uninitialized state and `f()` failed, an error is returned.
     ///
     /// # Panics
     ///
-    /// If `f` panics, the panic is propagated to the caller, and the cell
-    /// remains uninitialized.
+    /// If `f()` panics, the panic is propagated to the caller, and the cell
+    /// remains in the uninitialized state.
     ///
     /// It is an error to reentrantly initialize the cell from `f`. Doing
     /// so results in a panic.
@@ -238,14 +244,14 @@ impl<T> OnceCell<T> {
         self.try_init(f)
     }
 
-    /// Gets the mutable reference of the contents of the cell, initializing
-    /// it with `f` if the cell was empty. If the cell was empty and `f` failed,
-    /// an error is returned.
+    /// Gets the mutable reference of the cell's value, initializing
+    /// it to `f()` if the cell was in the uninitialized state. If the cell
+    /// was in the uninitialized state and `f()` failed, an error is returned.
     ///
     /// # Panics
     ///
-    /// If `f` panics, the panic is propagated to the caller, and the cell
-    /// remains uninitialized.
+    /// If `f()` panics, the panic is propagated to the caller, and the cell
+    /// remains in the uninitialized state.
     ///
     /// # Examples
     ///
@@ -256,7 +262,7 @@ impl<T> OnceCell<T> {
     ///
     /// let mut cell: OnceCell<u32> = OnceCell::new();
     ///
-    /// // Failed initializers do not change the value
+    /// // Failed attempts to initialize cell's value has no effect on the cell
     /// assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err());
     /// assert!(cell.get().is_none());
     ///
@@ -295,7 +301,7 @@ impl<T> OnceCell<T> {
 
     /// Consumes the cell, returning the wrapped value.
     ///
-    /// Returns `None` if the cell was empty.
+    /// Returns `None` if the cell was in the uninitialized state.
     ///
     /// # Examples
     ///
@@ -321,7 +327,7 @@ impl<T> OnceCell<T> {
 
     /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
     ///
-    /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized.
+    /// Has no effect and returns `None` if the `OnceCell` is in the uninitialized state.
     ///
     /// Safety is guaranteed by requiring a mutable reference.
     ///