doc: Shared Value state

nix-bindings-expr/src/eval_state.rs

@@ -442,6 +442,8 @@ impl EvalState {
     /// Converts [thunks](https://nix.dev/manual/nix/latest/language/evaluation.html#laziness) to their evaluated form. Does not modify already-evaluated values.
     ///
     /// Does not perform deep evaluation of nested structures.
+    ///
+    /// See also: [Shared Evaluation State](Value#shared-evaluation-state)
     #[doc(alias = "evaluate")]
     #[doc(alias = "strict")]
     pub fn force(&mut self, v: &Value) -> Result<()> {
@@ -460,6 +462,8 @@ impl EvalState {
     /// Returns [`None`] if the value is an unevaluated [thunk](https://nix.dev/manual/nix/latest/language/evaluation.html#laziness).
     ///
     /// Returns [`Some`] if the value is already evaluated.
+    ///
+    /// See also: [Shared Evaluation State](Value#shared-evaluation-state)
     #[doc(alias = "type_of")]
     #[doc(alias = "value_type_lazy")]
     #[doc(alias = "nix_get_type")]

nix-bindings-expr/src/value.rs

@@ -65,6 +65,21 @@ impl ValueType {
 }
 
 /// A pointer to a [value](https://nix.dev/manual/nix/latest/language/types.html) or [thunk](https://nix.dev/manual/nix/2.31/language/evaluation.html?highlight=thunk#laziness), to be used with [`EvalState`][`crate::eval_state::EvalState`] methods.
+///
+/// # Shared Evaluation State
+///
+/// Multiple `Value` instances can reference the same underlying Nix value.
+/// This occurs when a `Value` is [cloned](Clone), or when multiple Nix
+/// expressions reference the same binding.
+///
+/// When any reference to a thunk is evaluated—whether through
+/// [`force`](crate::eval_state::EvalState::force), other `EvalState` methods,
+/// or indirectly as a consequence of evaluating something else—all references
+/// observe the evaluated result. This means
+/// [`value_type_unforced`](crate::eval_state::EvalState::value_type_unforced)
+/// can return `None` (thunk) initially but a specific type later, even without
+/// directly operating on that `Value`. The state will not regress back to a
+/// less determined state.
 pub struct Value {
     inner: NonNull<raw::Value>,
 }