Lots of small fixes to docs in the turbo-tasks crate (vercel/turborep…

…o#8651)

### Description

Docs live here:
https://turbopack-rust-docs.vercel.sh/rustdoc/turbo_tasks/index.html

- Fixed lots of links.

- Export `VcCast`, `VcValueTypeCast`, and `VcValueTraitCast`, as they're
used in some type signatures, and some documentation is impossible to
follow without it. This introduces the sealed trait pattern to `VcCast`
to continue to strongly prevent foreign implementations.


### Testing Instructions

```
cargo doc --keep-going -p turbo-tasks
cargo doc --keep-going --document-private-items -p turbo-tasks
```

crates/turbo-tasks/src/backend.rs

@@ -121,7 +121,7 @@ impl PersistentTaskType {
     }
 
     /// Returns the name of the function in the code. Trait methods are
-    /// formatted as [`TraitName::method_name`].
+    /// formatted as `TraitName::method_name`.
     ///
     /// Equivalent to [`ToString::to_string`], but potentially more efficient as
     /// it can return a `&'static str` in many cases.
@@ -411,8 +411,8 @@ impl PersistentTaskType {
         Ok(turbo_tasks.dynamic_call(native_fn, resolved_inputs))
     }
 
-    /// Shared helper used by [`resolve_trait_method`] and
-    /// [`run_resolve_trait`].
+    /// Shared helper used by [`Self::resolve_trait_method`] and
+    /// [`Self::run_resolve_trait`].
     fn resolve_trait_method_from_value(
         trait_type: TraitTypeId,
         this_value: ConcreteTaskInput,

crates/turbo-tasks/src/completion.rs

@@ -1,6 +1,6 @@
 use crate::{self as turbo_tasks, RawVc, TryJoinIterExt, Vc};
 /// Just an empty type, but it's never equal to itself.
-/// [Vc<Completion>] can be used as return value instead of `()`
+/// [`Vc<Completion>`] can be used as return value instead of `()`
 /// to have a concrete reference that can be awaited.
 /// It will invalidate the awaiting task everytime the referenced
 /// task has been executed.

crates/turbo-tasks/src/debug/mod.rs

@@ -13,10 +13,10 @@ mod vdbg;
 
 use internal::PassthroughDebug;
 
-/// The return type of `ValueDebug::dbg`.
+/// The return type of [`ValueDebug::dbg`].
 ///
-/// We don't use `Vc<RcStr>` directly because we don't want the
-/// `Debug`/`Display` representations to be escaped.
+/// We don't use [`Vc<RcStr>`][crate::RcStr] or [`String`] directly because we
+/// don't want the [`Debug`]/[`Display`] representations to be escaped.
 #[turbo_tasks::value]
 pub struct ValueDebugString(String);
 
@@ -46,8 +46,8 @@ impl ValueDebugString {
     }
 }
 
-/// `Debug`-like trait for `Vc` types, automatically derived when using
-/// `turbo_tasks::value` and `turbo_tasks::value_trait`.
+/// [`Debug`]-like trait for [`Vc`] types, automatically derived when using
+/// [`macro@turbo_tasks::value`] and [`turbo_tasks::value_trait`].
 ///
 /// # Usage
 ///
@@ -62,9 +62,9 @@ pub trait ValueDebug {
     fn dbg_depth(self: Vc<Self>, depth: usize) -> Vc<ValueDebugString>;
 }
 
-/// Use [autoref specialization] to implement `ValueDebug` for `T: Debug`.
+/// Use [autoref specialization] to implement [`ValueDebug`] for `T: Debug`.
 ///
-/// [autoref specialization] https://github.com/dtolnay/case-studies/blob/master/autoref-specialization/README.md
+/// [autoref specialization]: https://github.com/dtolnay/case-studies/blob/master/autoref-specialization/README.md
 pub trait ValueDebugFormat {
     fn value_debug_format(&self, depth: usize) -> ValueDebugFormatString;
 }

crates/turbo-tasks/src/lib.rs

@@ -107,8 +107,9 @@ pub use turbo_tasks_macros::{function, value, value_impl, value_trait, TaskInput
 pub use value::{TransientInstance, TransientValue, Value};
 pub use value_type::{TraitMethod, TraitType, ValueType};
 pub use vc::{
-    Dynamic, TypedForInput, Upcast, ValueDefault, Vc, VcCellNewMode, VcCellSharedMode,
-    VcDefaultRead, VcRead, VcTransparentRead, VcValueTrait, VcValueType,
+    Dynamic, TypedForInput, Upcast, ValueDefault, Vc, VcCast, VcCellNewMode, VcCellSharedMode,
+    VcDefaultRead, VcRead, VcTransparentRead, VcValueTrait, VcValueTraitCast, VcValueType,
+    VcValueTypeCast,
 };
 
 pub use crate::rcstr::RcStr;

crates/turbo-tasks/src/manager.rs

@@ -252,12 +252,12 @@ pub struct TurboTasks<B: Backend + 'static> {
 
 #[derive(Default)]
 struct CurrentTaskState {
-    /// Affected [Task]s, that are tracked during task execution
-    /// These tasks will be invalidated when the execution finishes
-    /// or before reading a cell value
+    /// Affected tasks, that are tracked during task execution. These tasks will
+    /// be invalidated when the execution finishes or before reading a cell
+    /// value.
     tasks_to_notify: Vec<TaskId>,
 
-    // true, if the current task has state in cells
+    /// True if the current task has state in cells
     stateful: bool,
 }
 
@@ -378,7 +378,7 @@ impl<B: Backend + 'static> TurboTasks<B> {
     }
 
     /// Calls a native function with arguments. Resolves arguments when needed
-    /// with a wrapper [Task].
+    /// with a wrapper task.
     pub fn dynamic_call(&self, func: FunctionId, inputs: Vec<ConcreteTaskInput>) -> RawVc {
         if inputs.iter().all(|i| i.is_resolved()) {
             self.native_call(func, inputs)
@@ -1283,12 +1283,12 @@ pub async fn run_once_with_reason<T: Send + 'static>(
     Ok(rx.await?)
 }
 
-/// see [TurboTasks] `dynamic_call`
+/// Calls [`TurboTasks::dynamic_call`] for the current turbo tasks instance.
 pub fn dynamic_call(func: FunctionId, inputs: Vec<ConcreteTaskInput>) -> RawVc {
     with_turbo_tasks(|tt| tt.dynamic_call(func, inputs))
 }
 
-/// see [TurboTasks] `trait_call`
+/// Calls [`TurboTasks::trait_call`] for the current turbo tasks instance.
 pub fn trait_call(
     trait_type: TraitTypeId,
     trait_fn_name: Cow<'static, str>,
@@ -1332,7 +1332,7 @@ pub fn current_task_for_testing() -> TaskId {
     CURRENT_TASK_ID.with(|id| *id)
 }
 
-/// Get an [Invalidator] that can be used to invalidate the current [Task]
+/// Get an [`Invalidator`] that can be used to invalidate the current task
 /// based on external events.
 pub fn get_invalidator() -> Invalidator {
     let handle = Handle::current();

crates/turbo-tasks/src/task/concrete_task_input.rs

@@ -330,8 +330,8 @@ impl<'de> Deserialize<'de> for SharedValue {
 ///
 /// When a task is called, all its arguments will be converted and stored as
 /// [`ConcreteTaskInput`]s. When the task is actually run, these inputs will be
-/// converted back into the argument types. This is handled by the [`TaskInput`]
-/// trait.
+/// converted back into the argument types. This is handled by the
+/// [`TaskInput`][crate::TaskInput] trait.
 #[allow(clippy::derived_hash_with_manual_eq)]
 #[derive(Debug, Hash, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, Default)]
 pub enum ConcreteTaskInput {

crates/turbo-tasks/src/task/function.rs

@@ -10,7 +10,7 @@
 //! of its arguments implement `TaskInput` and its return type implements
 //! `TaskOutput`. There are a few hoops one needs to jump through to make this
 //! work, but they are described in this blog post:
-//! https://blog.logrocket.com/rust-bevy-entity-component-system/
+//! <https://blog.logrocket.com/rust-bevy-entity-component-system/>
 //!
 //! However, there is an additional complication in our case: async methods
 //! that accept a reference to the receiver as their first argument.

crates/turbo-tasks/src/task/task_input.rs

@@ -13,7 +13,7 @@ use crate::{
 };
 
 /// Trait to implement in order for a type to be accepted as a
-/// `turbo_tasks::function` argument.
+/// [`#[turbo_tasks::function]`][crate::function] argument.
 ///
 /// See also [`ConcreteTaskInput`].
 pub trait TaskInput: Send + Sync + Clone {

crates/turbo-tasks/src/trait_ref.rs

@@ -9,9 +9,10 @@ use crate::{
     RawVc, ReadRawVcFuture, SharedReference, Vc, VcValueTrait,
 };
 
-/// Similar to a [`ReadRef<T>`], but contains a value trait object instead. The
-/// only way to interact with a `TraitRef<T>` is by passing it around or turning
-/// it back into a value trait vc by calling [`ReadRef::cell`].
+/// Similar to a [`ReadRef<T>`][crate::ReadRef], but contains a value trait
+/// object instead. The only way to interact with a `TraitRef<T>` is by passing
+/// it around or turning it back into a value trait vc by calling
+/// [`ReadRef::cell`][crate::ReadRef::cell].
 ///
 /// Internally it stores a reference counted reference to a value on the heap.
 pub struct TraitRef<T>

crates/turbo-tasks/src/triomphe_utils.rs

@@ -2,8 +2,8 @@ use std::any::Any;
 
 use unsize::Coercion;
 
-/// Attempt to downcast a `triomphe::Arc<dyn Any + Send + Sync>` to a concrete
-/// type.
+/// Attempt to downcast a [`triomphe::Arc<dyn Any + Send +
+/// Sync>`][`triomphe::Arc`] to a concrete type.
 ///
 /// Ported from [`std::sync::Arc::downcast`] to [`triomphe::Arc`].
 pub fn downcast_triomphe_arc<T: Any + Send + Sync>(
@@ -25,7 +25,7 @@ pub fn downcast_triomphe_arc<T: Any + Send + Sync>(
     }
 }
 
-/// [`Coerce::to_any`] except that it coerces to `dyn Any + Send + Sync` as
+/// [`Coercion::to_any`] except that it coerces to `dyn Any + Send + Sync` as
 /// opposed to `dyn Any`.
 pub fn coerce_to_any_send_sync<T: Any + Send + Sync>() -> Coercion<T, dyn Any + Send + Sync> {
     // SAFETY: The signature of this function guarantees the coercion is valid

crates/turbo-tasks/src/vc/cast.rs

@@ -5,16 +5,17 @@ use anyhow::Result;
 use crate::{backend::CellContent, ReadRef, TraitRef, VcRead, VcValueTrait, VcValueType};
 
 /// Trait defined to share behavior between values and traits within
-/// [`ReadRawVcFuture`]. See [`ValueCast`] and [`TraitCast`].
+/// [`ReadRawVcFuture`][crate::ReadRawVcFuture]. See [`VcValueTypeCast`] and
+/// [`VcValueTraitCast`].
 ///
-/// This should not be implemented by users.
-pub trait VcCast {
+/// This trait is sealed and cannot be implemented by users.
+pub trait VcCast: private::Sealed {
     type Output;
 
     fn cast(content: CellContent) -> Result<Self::Output>;
 }
 
-/// Casts an arbitrary cell content into a [`ReadRef<T, U>`].
+/// Casts an arbitrary cell content into a [`ReadRef<T>`].
 pub struct VcValueTypeCast<T> {
     _phantom: PhantomData<T>,
 }
@@ -64,3 +65,14 @@ where
         content.cast_trait::<T>()
     }
 }
+
+// Implement the sealed trait pattern for `VcCast`.
+// https://rust-lang.github.io/api-guidelines/future-proofing.html
+mod private {
+    use super::{VcValueTraitCast, VcValueTypeCast};
+    use crate::{VcValueTrait, VcValueType};
+
+    pub trait Sealed {}
+    impl<T> Sealed for VcValueTypeCast<T> where T: VcValueType {}
+    impl<T> Sealed for VcValueTraitCast<T> where T: VcValueTrait + ?Sized {}
+}

crates/turbo-tasks/src/vc/mod.rs

@@ -12,7 +12,7 @@ use serde::{Deserialize, Serialize};
 
 use self::cell_mode::VcCellMode;
 pub use self::{
-    cast::{VcValueTraitCast, VcValueTypeCast},
+    cast::{VcCast, VcValueTraitCast, VcValueTypeCast},
     cell_mode::{VcCellNewMode, VcCellSharedMode},
     default::ValueDefault,
     read::{VcDefaultRead, VcRead, VcTransparentRead},
@@ -30,7 +30,7 @@ use crate::{
 /// Turbo Engine backend implementation.
 ///
 /// In order to get a reference to the pointed value, you need to `.await` the
-/// [`Vc<T>`] to get a [`ReadRef<T>`]:
+/// [`Vc<T>`] to get a [`ReadRef<T>`][crate::ReadRef]:
 ///
 /// ```
 /// let some_vc: Vc<T>;

crates/turbo-tasks/src/vc/read.rs

@@ -2,7 +2,7 @@ use std::{any::Any, marker::PhantomData, mem::ManuallyDrop};
 
 use super::traits::VcValueType;
 
-/// Trait that controls [`Vc`]'s read representation.
+/// Trait that controls [`crate::Vc`]'s read representation.
 ///
 /// Has two implementations:
 /// * [`VcDefaultRead`]

crates/turbo-tasks/src/vc/traits.rs

@@ -2,14 +2,15 @@ use super::{cell_mode::VcCellMode, read::VcRead};
 use crate::{TraitTypeId, ValueTypeId};
 
 /// A trait implemented on all values types that can be put into a Value Cell
-/// ([`Vc<T>`]).
+/// ([`Vc<T>`][crate::Vc]).
 ///
 /// # Safety
 ///
 /// The implementor of this trait must ensure that the read and cell mode
 /// implementations are correct for the value type. Otherwise, it is possible to
-/// generate invalid reads, for instance by using `VcTransparentRead` for a
-/// value type that is not repr(transparent).
+/// generate invalid reads, for instance by using
+/// [`VcTransparentRead`][crate::VcTransparentRead] for a value type that is not
+/// `#[repr(transparent)]`.
 pub unsafe trait VcValueType: Sized + Send + Sync + 'static {
     /// How to read the value.
     type Read: VcRead<Self>;
@@ -22,13 +23,13 @@ pub unsafe trait VcValueType: Sized + Send + Sync + 'static {
 }
 
 /// A trait implemented on all values trait object references that can be put
-/// into a Value Cell ([`Vc<&dyn Trait>`]).
+/// into a Value Cell ([`Vc<&dyn Trait>`][crate::Vc]).
 pub trait VcValueTrait {
     fn get_trait_type_id() -> TraitTypeId;
 }
 
-/// Marker trait that indicates that a [`Vc<Self>`] can be upcasted to a
-/// [`Vc<T>`].
+/// Marker trait that indicates that a [`Vc<Self>`][crate::Vc] can be upcasted
+/// to a [`Vc<T>`][crate::Vc].
 ///
 /// # Safety
 ///
@@ -40,8 +41,8 @@ where
 {
 }
 
-/// Marker trait that indicates that a [`Vc<Self>`] can accept all methods
-/// declared on a [`Vc<T>`].
+/// Marker trait that indicates that a [`Vc<Self>`][crate::Vc] can accept all
+/// methods declared on a [`Vc<T>`][crate::Vc].
 ///
 /// # Safety
 ///
@@ -54,7 +55,8 @@ where
 }
 
 /// Marker trait that a turbo_tasks::value is prepared for
-/// serialization as Value<...> input.
-/// Either use `#[turbo_tasks::value(serialization: auto_for_input)]`
-/// or avoid Value<...> in favor of a real Vc
+/// serialization as [`Value<...>`][crate::Value] input.
+/// Either use [`#[turbo_tasks::value(serialization:
+/// auto_for_input)]`][macro@crate::value] or avoid [`Value<...>`][crate::Value]
+/// in favor of a real [Vc][crate::Vc].
 pub trait TypedForInput: VcValueType {}