Improve documentation comments

turbopack/crates/turbo-tasks/src/manager.rs

@@ -1587,6 +1587,10 @@ impl CurrentCellRef {
     /// However, in most cases, the default derived implementation of
     /// `PartialEq` is used which just forwards to the inner value's
     /// `PartialEq`.
+    ///
+    /// If you already have a `SharedReference`, consider calling
+    /// [`compare_and_update_with_shared_reference`] which can re-use the
+    /// `SharedReference` object.
     pub fn compare_and_update<T>(&self, new_value: T)
     where
         T: PartialEq + VcValueType,

turbopack/crates/turbo-tasks/src/vc/cell_mode.rs

@@ -17,8 +17,12 @@ where
     /// Create a new cell.
     fn cell(value: VcReadTarget<T>) -> Vc<T>;
 
-    /// Create a type-erased `RawVc` cell given a pre-existing type-erased
-    /// `SharedReference`. In some cases, we will re-use the shared value.
+    /// Create a type-erased [`RawVc`] cell given a pre-existing type-erased
+    /// [`SharedReference`][crate::task::SharedReference].
+    ///
+    /// This is used in APIs that already have a `SharedReference`, such as in
+    /// [`ReadRef::cell`][crate::ReadRef::cell] or in [`Vc::resolve`] when
+    /// resolving a local [`Vc`]. This avoids unnecessary cloning.
     fn raw_cell(value: TypedSharedReference) -> RawVc;
 }