Unverified Commit 7e817e86 authored by Marcos Hernanz's avatar Marcos Hernanz Committed by GitHub

Fix Rust doctest failures (#95909)

## Summary

- Fix Rust documentation examples so workspace doctests compile
successfully.
- Mark incomplete illustrative snippets as ignored while keeping
runnable examples checked.
- Update stale imports and API usage, and classify directory trees as
text.

## Verification

- cargo fmt --all -- --check
- cargo test --workspace --doc --no-fail-fast
- autoreview --mode local --stream-engine-output (Codex + Claude: 0
findings)
parent 42ccb2ee
...@@ -206,20 +206,24 @@ struct PlainDirectoryTree { ...@@ -206,20 +206,24 @@ struct PlainDirectoryTree {
/// ///
/// For example, given this directory structure: /// For example, given this directory structure:
/// ///
/// app/ /// ```text
/// ├── (group1)/ /// app/
/// │ └── products/ /// ├── (group1)/
/// │ └── sale/ /// │ └── products/
/// └── (group2)/ /// │ └── sale/
/// └── products/ /// └── (group2)/
/// └── [id]/ /// └── products/
/// └── [id]/
/// ```
/// ///
/// The UrlSegmentTree would be: /// The UrlSegmentTree would be:
/// ///
/// (root) /// ```text
/// └── products/ /// (root)
/// ├── sale/ /// └── products/
/// └── [id]/ /// ├── sale/
/// └── [id]/
/// ```
/// ///
/// This makes it easy to find all siblings at a given URL level. /// This makes it easy to find all siblings at a given URL level.
#[derive(Clone, Debug, Default, PartialEq, Eq, TraceRawVcs, NonLocalValue, Encode, Decode)] #[derive(Clone, Debug, Default, PartialEq, Eq, TraceRawVcs, NonLocalValue, Encode, Decode)]
......
...@@ -10,9 +10,8 @@ ...@@ -10,9 +10,8 @@
//! # Example //! # Example
//! //!
//! ``` //! ```
//! use std::hash::{BuildHasherDefault, RandomState, Hash}; //! use std::{collections::HashMap, hash::{Hash, RandomState}};
//! //!
//! use rustc_hash::FxHashMap;
//! use turbo_prehash::{BuildHasherExt, PreHashed}; //! use turbo_prehash::{BuildHasherExt, PreHashed};
//! //!
//! /// hash a key, returning a prehashed value //! /// hash a key, returning a prehashed value
...@@ -21,7 +20,7 @@ ...@@ -21,7 +20,7 @@
//! } //! }
//! //!
//! // create hashmap to hold pre-hashed values //! // create hashmap to hold pre-hashed values
//! let mut map: FxHashMap<PreHashed<String>, String> = FxHashMap::default(); //! let mut map: HashMap<PreHashed<String>, String> = HashMap::default();
//! //!
//! // insert a prehashed value //! // insert a prehashed value
//! let hashed_key = hash_key("hello".to_string()); //! let hashed_key = hash_key("hello".to_string());
......
...@@ -20,7 +20,7 @@ use crate::{ ...@@ -20,7 +20,7 @@ use crate::{
/// ///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```ignore
/// use turbo_tasks::{Vc}; /// use turbo_tasks::{Vc};
/// ///
/// #[turbo_tasks::function(fs)] /// #[turbo_tasks::function(fs)]
......
...@@ -8,7 +8,7 @@ read. These macros handle that automatically. ...@@ -8,7 +8,7 @@ read. These macros handle that automatically.
Returns `Result<RcStr>` after resolving all arguments asynchronously. Returns `Result<RcStr>` after resolving all arguments asynchronously.
```rust ```ignore
// Positional arguments // Positional arguments
let msg = turbofmt!("asset {} in path {}", asset.ident(), base_path).await?; let msg = turbofmt!("asset {} in path {}", asset.ident(), base_path).await?;
...@@ -28,7 +28,7 @@ formatting directly and are **not** resolved asynchronously. ...@@ -28,7 +28,7 @@ formatting directly and are **not** resolved asynchronously.
Same as `turbofmt!`, but calls `anyhow::bail!()` with the formatted message. Same as `turbofmt!`, but calls `anyhow::bail!()` with the formatted message.
Has implicit `.await` and return flow. Has implicit `.await` and return flow.
```rust ```ignore
turbobail!("asset {} is not in path {}", asset.ident(), base_path); turbobail!("asset {} is not in path {}", asset.ident(), base_path);
``` ```
...@@ -40,14 +40,14 @@ and `ResolvedVc<T>` fields work directly in format strings. ...@@ -40,14 +40,14 @@ and `ResolvedVc<T>` fields work directly in format strings.
**No attribute** — delegates to `Display::to_string()`: **No attribute** — delegates to `Display::to_string()`:
```rust ```ignore
#[derive(ValueToString)] #[derive(ValueToString)]
struct Foo { ... } // requires Display impl struct Foo { ... } // requires Display impl
``` ```
**Format string with field references** — fields are resolved async: **Format string with field references** — fields are resolved async:
```rust ```ignore
#[derive(ValueToString)] #[derive(ValueToString)]
#[value_to_string("[{fs}]/{path}")] #[value_to_string("[{fs}]/{path}")]
struct FileSystemPath { fs: ResolvedVc<...>, path: RcStr } struct FileSystemPath { fs: ResolvedVc<...>, path: RcStr }
...@@ -55,7 +55,7 @@ struct FileSystemPath { fs: ResolvedVc<...>, path: RcStr } ...@@ -55,7 +55,7 @@ struct FileSystemPath { fs: ResolvedVc<...>, path: RcStr }
**Format string with explicit expressions:** **Format string with explicit expressions:**
```rust ```ignore
#[derive(ValueToString)] #[derive(ValueToString)]
#[value_to_string("{}", self.name())] #[value_to_string("{}", self.name())]
struct Bar { ... } struct Bar { ... }
...@@ -63,7 +63,7 @@ struct Bar { ... } ...@@ -63,7 +63,7 @@ struct Bar { ... }
**Direct expression:** **Direct expression:**
```rust ```ignore
#[derive(ValueToString)] #[derive(ValueToString)]
#[value_to_string(self.inner)] #[value_to_string(self.inner)]
struct Wrapper { inner: RcStr } struct Wrapper { inner: RcStr }
...@@ -71,7 +71,7 @@ struct Wrapper { inner: RcStr } ...@@ -71,7 +71,7 @@ struct Wrapper { inner: RcStr }
**Enums** — variants without an attribute default to their name: **Enums** — variants without an attribute default to their name:
```rust ```ignore
#[derive(ValueToString)] #[derive(ValueToString)]
enum Kind { enum Kind {
Foo, // → "Foo" Foo, // → "Foo"
...@@ -87,7 +87,7 @@ enum Kind { ...@@ -87,7 +87,7 @@ enum Kind {
The underlying async trait. You rarely need to implement this manually — The underlying async trait. You rarely need to implement this manually —
prefer `#[derive(ValueToString)]` instead. prefer `#[derive(ValueToString)]` instead.
```rust ```ignore
#[turbo_tasks::value_trait] #[turbo_tasks::value_trait]
pub trait ValueToString { pub trait ValueToString {
fn to_string(self: Vc<Self>) -> Vc<RcStr>; fn to_string(self: Vc<Self>) -> Vc<RcStr>;
......
Tasks are created by defining a Rust function annotated with the `#[turbo_tasks::function]` macro and calling it with arguments. Each unique combination of function and arguments create a new task at runtime. Tasks are the fundamental units of work within the build system. Tasks are created by defining a Rust function annotated with the `#[turbo_tasks::function]` macro and calling it with arguments. Each unique combination of function and arguments create a new task at runtime. Tasks are the fundamental units of work within the build system.
```rust ```ignore
#[turbo_tasks::function] #[turbo_tasks::function]
fn add(a: i32, b: i32) -> Vc<Something> { fn add(a: i32, b: i32) -> Vc<Something> {
// Task implementation goes here... // Task implementation goes here...
...@@ -65,7 +65,7 @@ async fn foo( ...@@ -65,7 +65,7 @@ async fn foo(
will have an external signature of will have an external signature of
```rust ```ignore
fn foo( fn foo(
self: Vc<Self>, // was: &self self: Vc<Self>, // was: &self
a: i32, a: i32,
...@@ -80,7 +80,7 @@ fn foo( ...@@ -80,7 +80,7 @@ fn foo(
The `#[turbo_tasks::function]` macro accepts optional attributes that modify the behavior of the The `#[turbo_tasks::function]` macro accepts optional attributes that modify the behavior of the
task. Multiple attributes can be combined by separating them with commas. task. Multiple attributes can be combined by separating them with commas.
```rust ```ignore
#[turbo_tasks::function(fs, session_dependent)] #[turbo_tasks::function(fs, session_dependent)]
async fn read_file(path: RcStr) -> Result<Vc<FileContent>> { async fn read_file(path: RcStr) -> Result<Vc<FileContent>> {
// ... // ...
...@@ -155,7 +155,7 @@ Tasks can be methods associated with a value or a trait implementation using the ...@@ -155,7 +155,7 @@ Tasks can be methods associated with a value or a trait implementation using the
### Inherent Implementations ### Inherent Implementations
```rust ```ignore
#[turbo_tasks::value_impl] #[turbo_tasks::value_impl]
impl Something { impl Something {
#[turbo_tasks::function] #[turbo_tasks::function]
...@@ -201,7 +201,7 @@ impl Something { ...@@ -201,7 +201,7 @@ impl Something {
### Trait Implementations ### Trait Implementations
```rust ```ignore
#[turbo_tasks::value_impl] #[turbo_tasks::value_impl]
impl Trait for Something { impl Trait for Something {
#[turbo_tasks::function] #[turbo_tasks::function]
......
...@@ -266,7 +266,9 @@ impl EffectStateStorage { ...@@ -266,7 +266,9 @@ impl EffectStateStorage {
/// # #![feature(arbitrary_self_types_pointers)] /// # #![feature(arbitrary_self_types_pointers)]
/// # /// #
/// # use anyhow::Result; /// # use anyhow::Result;
/// # use turbo_tasks::{Effects, ReadRef, Vc, run_once, take_effects}; /// # use turbo_tasks::{
/// # Effects, ReadRef, Vc, read_strongly_consistent_and_apply_effects, take_effects,
/// # };
/// # /// #
/// # async fn _wrapper() -> Result<()> { /// # async fn _wrapper() -> Result<()> {
/// # type Example = (); /// # type Example = ();
...@@ -292,13 +294,13 @@ impl EffectStateStorage { ...@@ -292,13 +294,13 @@ impl EffectStateStorage {
/// Ok(OutputWithEffects { output, effects }.cell()) /// Ok(OutputWithEffects { output, effects }.cell())
/// } /// }
/// ///
/// // every operation must be read with strong consistency at the top-level /// // read with strong consistency and apply the effects once at the top-level
/// let result_with_effects = some_turbo_tasks_operation_with_effects(args) /// // (e.g. in a `run_once` closure)
/// .read_strongly_consistent() /// let _result_with_effects = read_strongly_consistent_and_apply_effects(
/// .await?; /// some_turbo_tasks_operation_with_effects(args),
/// /// |result| &result.effects,
/// // apply the effects once outside of a turbo_tasks::function at the top-level (e.g. `run_once`) /// )
/// result_with_effects.effects.apply().await?; /// .await?;
/// # Ok(()) /// # Ok(())
/// # } /// # }
/// ``` /// ```
......
...@@ -1982,12 +1982,13 @@ impl CurrentCellRef { ...@@ -1982,12 +1982,13 @@ impl CurrentCellRef {
/// ///
/// ``` /// ```
/// #[turbo_tasks::value(transparent, eq = "manual")] /// #[turbo_tasks::value(transparent, eq = "manual")]
/// #[derive(Clone)]
/// struct Wrapper(Vec<u32>); /// struct Wrapper(Vec<u32>);
/// ///
/// impl PartialEq for Wrapper { /// impl PartialEq for Wrapper {
/// fn eq(&self, other: Wrapper) { /// fn eq(&self, other: &Wrapper) -> bool {
/// // Example: order doesn't matter for equality /// // Example: order doesn't matter for equality
/// let (mut this, mut other) = (self.clone(), other.clone()); /// let (mut this, mut other) = (self.0.clone(), other.0.clone());
/// this.sort_unstable(); /// this.sort_unstable();
/// other.sort_unstable(); /// other.sort_unstable();
/// this == other /// this == other
......
...@@ -163,6 +163,9 @@ pub struct TimingEvent { ...@@ -163,6 +163,9 @@ pub struct TimingEvent {
/// ///
/// Example: /// Example:
/// ```rust /// ```rust
/// use std::time::Duration;
/// use turbo_tasks::message_queue::{CompilationEvent, TimingEvent};
///
/// let event = TimingEvent::new("Compiled successfully".to_string(), Duration::from_millis(100)); /// let event = TimingEvent::new("Compiled successfully".to_string(), Duration::from_millis(100));
/// let message = event.message(); /// let message = event.message();
/// assert_eq!(message, "Compiled successfully in 100ms"); /// assert_eq!(message, "Compiled successfully in 100ms");
......
...@@ -90,7 +90,12 @@ impl<'a, T> Unpin for CloneReady<'a, T> {} ...@@ -90,7 +90,12 @@ impl<'a, T> Unpin for CloneReady<'a, T> {}
/// Structs or enums can be made into task inputs by deriving `TaskInput`: /// Structs or enums can be made into task inputs by deriving `TaskInput`:
/// ///
/// ```rust /// ```rust
/// # use turbo_tasks::{
/// # macro_helpers::bincode::{Decode, Encode},
/// # trace::TraceRawVcs,
/// # };
/// #[turbo_tasks::task_input] /// #[turbo_tasks::task_input]
/// #[derive(Clone, Debug, PartialEq, Eq, Hash, TraceRawVcs, Encode, Decode)]
/// struct MyStruct { /// struct MyStruct {
/// // Fields go here... /// // Fields go here...
/// } /// }
......
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
In order to get a reference to the pointed value, you need to `.await` the [`Vc<T>`] to get a [`ReadRef<T>`][`ReadRef`]: In order to get a reference to the pointed value, you need to `.await` the [`Vc<T>`] to get a [`ReadRef<T>`][`ReadRef`]:
``` ```ignore
let some_vc: Vc<T>; let some_vc: Vc<T>;
let some_ref: ReadRef<T> = some_vc.await?; let some_ref: ReadRef<T> = some_vc.await?;
some_ref.some_method_on_t(); some_ref.some_method_on_t();
......
...@@ -392,7 +392,7 @@ where ...@@ -392,7 +392,7 @@ where
/// usecases. /// usecases.
/// ///
/// # Example /// # Example
/// ```rust /// ```ignore
/// // In generic code where T might be the same as K /// // In generic code where T might be the same as K
/// fn process_foo(vc: ResolvedVc<impl Upcast<Box<dyn MyTrait>>>) -> Vc<Foo> { /// fn process_foo(vc: ResolvedVc<impl Upcast<Box<dyn MyTrait>>>) -> Vc<Foo> {
/// let my_trait: ResolvedVc<Box<dyn MyTrait>> = Vc::upcast_non_strict(vc); /// let my_trait: ResolvedVc<Box<dyn MyTrait>> = Vc::upcast_non_strict(vc);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment