Unverified Commit 4084a0f4 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

Enforce strict rustdoc (incl. private items) across the Rust workspace (#100768)

### What?

Makes rustdoc warnings fail CI for the whole Rust workspace, including
private items, and fixes every existing warning so the new check starts
green.

- New `scripts/check-rustdoc.sh` runs `RUSTDOCFLAGS="-D warnings" cargo
doc --workspace --no-deps --document-private-items`.
- The existing `rustdoc check` job in `build_and_test.yml` now runs that
script before `scripts/deploy-turbopack-docs.sh`. The public `next-*`
docs build is unchanged.
- Fixes the warnings across the workspace's Rust crates (turbo-tasks,
turbo-tasks-backend, turbo-persistence, turbopack-*, next-core,
next-api, next-napi-bindings, …).

### Why?

The existing `rustdoc check` job only documented the public items of
five `next-*` crates and didn't treat warnings as errors. Broken
intra-doc links and other rustdoc warnings went unnoticed everywhere
else. Running strict private-items docs over the whole workspace found
about 60 of them.

### How?

The Rust source changes are doc comments only. The only other doc edit
is one link target in `singleton_pattern.md`. Nothing is silenced with
`#[allow]`, and no imports or visibility changes were added for docs.
Types of fix:

- **Unresolved links**: point to the correct full path
(`turbo_tasks::…`, `crate::…`, `Self::…`). Some links named renamed or
moved items, for example `Effect::apply` → `CapturedEffect::apply` and
`dec_in_flight` → `decrement_in_flight`. Those now point to the current
item.
- **Links to items rustdoc can't link to**: plain code text. These are
test-only or feature-gated items, `doc(hidden)` items, private items in
another crate, and a private trait rustdoc doesn't resolve.
- **Ambiguous `crate::value`** (module and macro): `macro@crate::value`.
- **Bare URLs**: wrapped in `<…>`.
- **Unclosed HTML tags** from generics such as `Option<T>`: put in
backticks.
- **Redundant explicit link targets**: removed.

The check runs with the workspace's default features on the CI target.
It doesn't cover every feature or platform combination.

### Verification

- `./scripts/check-rustdoc.sh && ./scripts/deploy-turbopack-docs.sh`
(the exact CI step) passes locally.
- `RUSTDOCFLAGS='-D warnings' cargo doc --workspace --no-deps` (public
items) passes.
- Negative check: a temporary broken intra-doc link made
`scripts/check-rustdoc.sh` exit non-zero.
- `cargo fmt --all --check` is clean.

<!-- NEXT_JS_LLM -->


<!-- fleet 4bbc2447-5ae3-4b88-9649-a6b5ff30491e -->

---------
Co-authored-by: 's avatarvercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by: 's avatarTobias Koppers <1365881+sokra@users.noreply.github.com>
Co-authored-by: 's avatarNiklas Mischkulnig <4586894+mischnic@users.noreply.github.com>
parent 05d13d45
......@@ -387,7 +387,7 @@ jobs:
needsRust: 'yes'
skipInstallBuild: 'yes'
skipNativeBuild: 'yes'
afterBuild: ./scripts/deploy-turbopack-docs.sh
afterBuild: ./scripts/check-rustdoc.sh && ./scripts/deploy-turbopack-docs.sh
stepName: 'rustdoc-check'
secrets: inherit
......
......@@ -98,8 +98,8 @@ impl VersionedContentMap {
#[turbo_tasks::value_impl]
impl VersionedContentMap {
/// Lists the aggregate-HMR *entry* chunks under `root` with their
/// [`VersionedContent`], sorted by path. Only Node.js chunk-list content is
/// returned. Callers scope which
/// [`VersionedContent`](turbopack_core::version::VersionedContent), sorted by path. Only
/// Node.js chunk-list content is returned. Callers scope which
/// entries are included by narrowing `root` (e.g. the aggregate server-HMR
/// subscription passes `server/app` to include App Router entries only).
///
......
......@@ -15,7 +15,7 @@ use turbopack_ecmascript::{
use super::module_rule_match_js_no_url;
/// A [`TaskInput`]-compatible mirror of [`ExportFilter`].
/// A [`TaskInput`](turbo_tasks::TaskInput)-compatible mirror of [`ExportFilter`].
#[turbo_tasks::task_input]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Encode, Decode)]
enum ExportFilterInput {
......
......@@ -744,8 +744,8 @@ impl CompilationEvent for SlowFilesystemEvent {
/// more than `SLOW_FILESYSTEM_THRESHOLD`.
///
/// This idea is copied from Bun:
/// - https://x.com/jarredsumner/status/1637549427677364224
/// - https://github.com/oven-sh/bun/blob/06a9aa80c38b08b3148bfeabe560/src/install/install.zig#L3038
/// - <https://x.com/jarredsumner/status/1637549427677364224>
/// - <https://github.com/oven-sh/bun/blob/06a9aa80c38b08b3148bfeabe560/src/install/install.zig#L3038>
async fn benchmark_file_io(turbo_tasks: &NextTurboTasks, dir: &Path) -> Result<()> {
let temp_path = dir.join(format!(
"tmp_file_io_benchmark_{:x}",
......
#!/usr/bin/env bash
set -euo pipefail
# Build rustdoc for every crate in the Cargo workspace, including private items, and fail on any
# rustdoc warning (broken intra-doc links, bare URLs, unclosed HTML tags, ...).
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --document-private-items
......@@ -20,7 +20,7 @@ mod ser;
/// Uses a u8 representation, which is slightly more efficient than bincode's default u32 varint
/// approach for enum discriminants:
/// https://docs.rs/bincode/latest/bincode/spec/index.html#discriminant-representation
/// <https://docs.rs/bincode/latest/bincode/spec/index.html#discriminant-representation>
#[derive(Copy, Clone, PartialEq, Eq)]
#[repr(u8)]
enum TypeTag {
......
......@@ -18,7 +18,7 @@ struct ActiveIterator<T: Iterator<Item = Result<LookupEntry>>> {
/// A heap node that keeps the hash inline alongside a boxed `ActiveIterator`. By hoisting the hash
/// out of the Box we avoid a pointer chase on every comparison when the heap is re-ordered Only
/// when hashes collide (extremely rare with u64) do we dereference the Box to compare keys.
/// Note: we cannot use [Prehashed] because we need an non-trivial `Ord` implementation for the heap
/// Note: we cannot use `Prehashed` because we need an non-trivial `Ord` implementation for the heap
/// (see below)
struct HeapNode<T: Iterator<Item = Result<LookupEntry>>> {
/// Cached copy of the current entry's hash, kept in sync with `inner.entry.hash`.
......
......@@ -66,7 +66,8 @@ pub(crate) const META_FILE_MAGIC: u32 = 0xFE4ADA4A;
/// On-disk layout of a single entry header in the `.meta` file.
///
/// Fields are big-endian to match the existing wire format written by [`MetaFileBuilder`].
/// Fields are big-endian to match the existing wire format written by
/// [`MetaFileBuilder`](crate::meta_file_builder::MetaFileBuilder).
#[repr(C, packed)]
#[derive(FromBytes, IntoBytes, Immutable, KnownLayout, Clone, Copy)]
pub(crate) struct EntryHeader {
......
......@@ -147,7 +147,7 @@ impl KeyBlockFormat {
}
}
/// Copy-able snapshot of the accumulator state needed by [`flush_key_block`].
/// Copy-able snapshot of the accumulator state needed by [`StreamingSstWriter::flush_key_block`].
#[derive(Clone, Copy)]
struct KeyBlockFlushInfo {
max_key_len: usize,
......@@ -871,7 +871,7 @@ impl<E: Entry> StreamingSstWriter<E> {
/// Advances `first_pending_small_index` past the just-pushed entry if it is resolved and
/// sits right at the current boundary. Flushes complete key blocks incrementally.
///
/// Must be called immediately after [`push_pending_key_entry`] with a resolved
/// Must be called immediately after [`Self::push_pending_key_entry`] with a resolved
/// (non-`PendingSmall`) entry.
fn try_flush_key_blocks(&mut self) -> Result<()> {
debug_assert!(!matches!(
......@@ -1174,7 +1174,7 @@ impl<E: Entry> StreamingSstWriter<E> {
/// Flushes all remaining entries as key blocks. Called from `close()` after all small value
/// blocks have been flushed, so all PendingSmall entries are resolved.
///
/// This loop mirrors [`advance_boundary_to`], but uses a local accumulator (since the
/// This loop mirrors [`Self::advance_boundary_to`], but uses a local accumulator (since the
/// `self.current_key_block` state is stale) and flushes the final incomplete block
/// (unlike `advance_boundary_to`, which keeps it for more entries during streaming).
fn flush_remaining_key_blocks(&mut self) -> Result<()> {
......@@ -1330,8 +1330,9 @@ const FIXED_KEY_BLOCK_HEADER_SIZE: usize = 6;
/// search probes are contiguous: the search region holds only what the lookup compares first (the
/// hash for `HashThenKey`, the key for `KeyOnly`), and everything else follows in the tail region,
/// addressed by the same entry index. [`FixedRegions`] derives that geometry for both this builder
/// and the reader; see [`KEY_BLOCK_TABLE_ENTRY_SIZE_WITH_HASH`] for why the compared bytes are
/// hoisted out of the payload.
/// and the reader; see
/// [`KEY_BLOCK_TABLE_ENTRY_SIZE_WITH_HASH`](crate::static_sorted_file::KEY_BLOCK_TABLE_ENTRY_SIZE_WITH_HASH)
/// for why the compared bytes are hoisted out of the payload.
struct FixedKeyBlockBuilder<'l> {
/// Receives the header and then the search region.
buffer: &'l mut Vec<u8>,
......
......@@ -15,7 +15,7 @@ use std::str::FromStr;
use proc_macro::{Literal, TokenStream, TokenTree};
/// `MAX_INLINE_LEN` for the active `turbo-rcstr` configuration. Mirrors
/// [`turbo_rcstr::tagged_value::MAX_INLINE_LEN`]
/// `turbo_rcstr::tagged_value::MAX_INLINE_LEN`.
const MAX_INLINE_LEN: usize = if cfg!(feature = "atom_size_128") {
15
} else {
......
......@@ -45,7 +45,7 @@ pub unsafe fn restore_arc(v: TaggedValue) -> Arc<DynamicPrehashedString> {
unsafe { Arc::from_raw(ptr) }
}
/// This can create any kind of [Atom], although this lives in the `dynamic`
/// This can create any kind of [`RcStr`], although this lives in the `dynamic`
/// module.
///
/// Takes a [`Cow`] rather than a `&str` so that an already-owned string can be moved into the atom
......
......@@ -561,7 +561,7 @@ macro_rules! __rcstr_static_submit {
/// Read-only lookup table mapping precomputed hash -> static StaticPrehashedString.
/// Built once on first access from all `rcstr!` constants gathered at link time into
/// [`STATIC_RCSTRS`].
/// `STATIC_RCSTRS`.
///
/// Multiple `rcstr!` calls with the same string content will each scatter an entry, but we
/// deduplicate by content here so only one entry per unique string is stored.
......
......@@ -26,9 +26,9 @@ use turbo_tasks::{
use crate::backend::storage_schema::{DropPartial, DropPartialOutcome, MergeRestore};
/// The value is stored as [`SharedReference`] rather than
/// [`TypedSharedReference`] because the `CellId` key already carries the
/// [`ValueTypeId`] — duplicating it in each map entry would waste memory.
/// Encode / decode recover the value type from the key.
/// [`TypedSharedReference`](turbo_tasks::TypedSharedReference) because the `CellId` key already
/// carries the [`ValueTypeId`](turbo_tasks::ValueTypeId) — duplicating it in each map entry would
/// waste memory. Encode / decode recover the value type from the key.
/// Default inline size is 1 because this optimizes storage layout and a non-trivial number of tasks
/// have <=1 cells
type InnerMap = AutoMap<CellId, SharedReference, BuildHasherDefault<FxHasher>, 1>;
......
......@@ -60,7 +60,9 @@ pub fn invalidate(
queue.execute(&mut ctx);
}
/// Requires the guard to be allocated with [TaskDataCategory::All]
/// Requires the guard to be allocated with [`TaskDataCategory::All`]
///
/// [`TaskDataCategory::All`]: crate::backend::storage::TaskDataCategory::All
pub fn make_task_dirty_internal(
task: &mut TaskGuard<'_>,
make_stale: bool,
......@@ -84,7 +86,9 @@ pub fn make_task_dirty_internal(
/// priority to schedule it with (see [`ExecuteContext::schedule_task`]). The task is already marked
/// as scheduled when this returns `Some`, so the caller must schedule it.
///
/// Requires the guard to be allocated with [TaskDataCategory::All]
/// Requires the guard to be allocated with [`TaskDataCategory::All`]
///
/// [`TaskDataCategory::All`]: crate::backend::storage::TaskDataCategory::All
#[must_use]
pub(super) fn make_task_dirty_without_scheduling(
task: &mut TaskGuard<'_>,
......
......@@ -218,7 +218,8 @@ impl SnapshotCoordinator {
/// operations from entering, then atomically close admission at a zero-active boundary.
///
/// Waits for as long as it takes. If the wait gets long, `on_slow_settle` is called after
/// [`SLOW_SETTLE_REPORT`] and again each time the total wait doubles.
/// the slow-settle report timeout (by default [`DEFAULT_SLOW_SETTLE_REPORT_TIME`]) and again
/// each time the total wait doubles.
///
/// Concurrent callers panic. Production callers
/// must serialize themselves (see `snapshot_in_progress` lock in
......
......@@ -346,7 +346,7 @@ pub struct Storage {
/// Maps `CachedTaskType` → `TaskId` for deduplication of persistent task creation.
/// This is backed by the TaskCache table in the database.
///
/// LockOrdering: See the comments on [map].
/// LockOrdering: See the comments on [`map`](Self::map).
pub task_cache: FxDashMap<CachedTaskTypeArc, TaskId>,
}
......
......@@ -334,7 +334,7 @@ impl InProgressState {
(InProgressState::Scheduled { done_event, reason }, listener)
}
}
/// Used by the [`get_mut`][crate::backend::storage::get_mut] macro to restrict mutable access to a
/// Used by the `get_mut` macro to restrict mutable access to a
/// subset of types. No mutable access should be allowed for persisted data, since that would break
/// persisting.
#[allow(non_upper_case_globals, dead_code)]
......
......@@ -109,7 +109,7 @@ pub(crate) fn invalidate_db(base_path: &Path, reason_code: &str) -> anyhow::Resu
/// This should be run with the base (non-versioned) path.
///
/// In most cases, you should prefer a higher-level API like
/// [`crate::KeyValueDatabaseBackingStorage::open_versioned_on_disk`] to this one.
/// [`TurboBackingStorage::open_versioned_on_disk`](crate::TurboBackingStorage::open_versioned_on_disk) to this one.
pub(crate) fn check_db_invalidation_and_cleanup(
base_path: &Path,
) -> anyhow::Result<StartupCacheState> {
......
......@@ -4,7 +4,8 @@ use std::{error::Error as StdError, fmt};
use turbo_tasks::NonLocalValue;
/// Wrapper to convert [`anyhow::Error`] to `impl std::error::Error` for use in [`Effect::apply`].
/// Wrapper to convert [`anyhow::Error`] to `impl std::error::Error` for use in
/// [`CapturedEffect::apply`](turbo_tasks::CapturedEffect::apply).
// TODO(bgw): use a structured error type instead of anyhow for write/write_link
#[derive(NonLocalValue)]
pub(crate) struct AnyhowWrapper(anyhow::Error);
......
......@@ -15,7 +15,7 @@ const MAX_RETRY_ATTEMPTS: usize = 10;
///
/// This used to use [`tokio::task::spawn_blocking`], but now the IO operation blocks the current
/// thread, as we already wrap callers of this function in
/// [`crate::ConcurrencyLimitedExt::concurrency_limited`] and it
/// `ConcurrencyLimitedExt::concurrency_limited` (in `disk.rs`) and it
/// appears to be faster to block the tokio thread than to spawn. Most of our IO operations are very
/// short anyways. See this PR: <https://github.com/vercel/next.js/pull/87661>.
pub(crate) async fn retry_blocking<T>(func: impl FnMut() -> io::Result<T>) -> io::Result<T> {
......
......@@ -249,8 +249,8 @@ impl State {
}
}
/// Used when [`DiskWatcherConfig::recursive_mode`] returns [`RecursiveMode::Recursive`] (default on
/// macOS and Windows when not polling).
/// Used when the resolved [`DiskWatcherConfig::recursive_mode`] is
/// [`DiskWatcherRecursiveMode::Recursive`] (default on macOS and Windows when not polling).
enum RecursiveState {
/// Used when [`DiskWatcher::start_watching`] hasn't been called yet or after
/// [`DiskWatcher::stop_watching`] is called.
......@@ -261,8 +261,8 @@ enum RecursiveState {
},
}
/// Used when [`DiskWatcherConfig::recursive_mode`] returns [`RecursiveMode::NonRecursive`] (default
/// on Linux, and everywhere when polling).
/// Used when the resolved [`DiskWatcherConfig::recursive_mode`] is
/// [`DiskWatcherRecursiveMode::NonRecursive`] (default on Linux, and everywhere when polling).
enum NonRecursiveState {
/// Used when [`DiskWatcher::start_watching`] hasn't been called yet or after
/// [`DiskWatcher::stop_watching`] is called.
......@@ -459,7 +459,7 @@ mod non_recursive_helpers {
///
/// Watches the given `dir_path` and every parent up to `root_path`. Parents must be recursively
/// watched in case any of them change:
/// https://docs.rs/notify/latest/notify/#parent-folder-deletion
/// <https://docs.rs/notify/latest/notify/#parent-folder-deletion>
fn start_watching_dir_and_parents(
state: &mut NonRecursiveWatchingState,
dir_path: &Path,
......
......@@ -53,7 +53,7 @@ struct FieldInfo {
field_type: Type,
storage_type: StorageType,
category: Category,
/// If true, field is lazily allocated in Vec<LazyField> (the default).
/// If true, field is lazily allocated in `Vec<LazyField>` (the default).
/// If false (marked with `inline`), field is stored directly on TaskStorage.
lazy: bool,
/// If true, filter out values that reference transient tasks during encoding.
......@@ -61,7 +61,7 @@ struct FieldInfo {
/// For collections: filter out entries where key/value is_transient() returns true.
filter_transient: bool,
/// If true, use Default::default() semantics instead of Option for inline direct fields.
/// The field type should be T (not Option<T>), and empty is represented by T::default().
/// The field type should be `T` (not `Option<T>`), and empty is represented by `T::default()`.
use_default: bool,
/// If true, shrink this collection after task execution completes.
/// Empty collections are removed entirely from the lazy vec.
......@@ -130,7 +130,8 @@ impl FieldInfo {
///
/// Used by mutators that track unconditionally (a replace/batch/counter update that reaches the
/// track call is always a real change), so the returned `TrackOutcome` is discarded with
/// `let _ =`. Mutators that track-then-undo use [`track_modification_outcome_expr`] instead.
/// `let _ =`. Mutators that track-then-undo use
/// [`track_modification_outcome_expr`](Self::track_modification_outcome_expr) instead.
fn track_modification_call(&self) -> TokenStream {
let field_name_str = self.field_name.to_string();
match self.category {
......@@ -148,13 +149,14 @@ impl FieldInfo {
}
}
/// [`track_modification_call`], but for `filter_transient` fields it only
/// fires when `key_expr` is not transient — transient entries are dropped at
/// [`track_modification_call`](Self::track_modification_call), but for `filter_transient`
/// fields it only fires when `key_expr` is not transient — transient entries are dropped at
/// encode (see [`generate_filter_predicate`]), so mutating one changes no
/// persistable bytes. Safe because tracking is monotonic (we only omit, never
/// clear). `key_expr` is the entry whose transience decides tracking and is
/// matched with `.is_transient()`. Identical to [`track_modification_call`]
/// for non-`filter_transient` fields.
/// matched with `.is_transient()`. Identical to
/// [`track_modification_call`](Self::track_modification_call) for non-`filter_transient`
/// fields.
fn track_modification_call_guarded(&self, key_expr: TokenStream) -> TokenStream {
if !self.filter_transient || self.is_transient() {
return self.track_modification_call();
......@@ -169,8 +171,9 @@ impl FieldInfo {
/// An *expression* (no trailing `;`) that calls `self.track_modification(...)` and evaluates to
/// a `TrackOutcome`. Used by mutators that track-before-mutate and then undo if the mutation
/// was a no-op (see [`track_modification_undo_expr`]). For transient *fields* there is nothing
/// to track, so it evaluates to `TrackOutcome::NoChange`.
/// was a no-op (see [`track_modification_undo_expr`](Self::track_modification_undo_expr)). For
/// transient *fields* there is nothing to track, so it evaluates to
/// `TrackOutcome::NoChange`.
fn track_modification_outcome_expr(&self) -> TokenStream {
let field_name_str = self.field_name.to_string();
match self.category {
......@@ -184,9 +187,10 @@ impl FieldInfo {
}
}
/// Like [`track_modification_outcome_expr`], but for `filter_transient` fields it only tracks
/// when `key_expr` is not transient (transient entries change no persistable bytes), evaluating
/// to `TrackOutcome::NoChange` otherwise. Identical to [`track_modification_outcome_expr`] for
/// Like [`track_modification_outcome_expr`](Self::track_modification_outcome_expr), but for
/// `filter_transient` fields it only tracks when `key_expr` is not transient (transient
/// entries change no persistable bytes), evaluating to `TrackOutcome::NoChange` otherwise.
/// Identical to [`track_modification_outcome_expr`](Self::track_modification_outcome_expr) for
/// non-`filter_transient` fields.
fn track_modification_outcome_expr_guarded(&self, key_expr: TokenStream) -> TokenStream {
if !self.filter_transient || self.is_transient() {
......@@ -3345,7 +3349,7 @@ fn gen_drop_lazy_match_arm(field: &FieldInfo) -> TokenStream {
}
}
/// Extract the inner type from Option<T>, or return the type as-is if not Option
/// Extract the inner type from `Option<T>`, or return the type as-is if not Option
fn extract_option_inner_type(ty: &Type) -> TokenStream {
// Try to parse as Option<T> and extract T
if let Type::Path(type_path) = ty
......@@ -3361,7 +3365,7 @@ fn extract_option_inner_type(ty: &Type) -> TokenStream {
quote! { #ty }
}
/// Extract the element type K from AutoSet<K> (which is FxHashSet<K>)
/// Extract the element type `K` from `AutoSet<K>` (which is `FxHashSet<K>`)
fn extract_set_element_type(ty: &Type) -> Option<TokenStream> {
if let Type::Path(type_path) = ty
&& let Some(segment) = type_path.path.segments.last()
......@@ -3776,7 +3780,7 @@ fn generate_encode_lazy_field_with_index(field: &FieldInfo, index: u8) -> TokenS
}
/// Generate code to encode lazy fields to bincode.
/// Uses sentinel-terminated format: [index, data]... [sentinel]
/// Uses sentinel-terminated format: `[index, data]... [sentinel]`
fn generate_encode_lazy_fields(fields: &[&FieldInfo]) -> TokenStream {
if fields.is_empty() {
return quote! {};
......
......@@ -5,7 +5,7 @@
//!
//! Builds without the `custom_allocator` feature additionally maintain a process-wide counter of
//! live bytes, which backs [`crate::TurboMalloc::memory_usage`]. With mimalloc that figure comes
//! from the allocator instead, so [`global`] is not compiled in: the atomic would otherwise be
//! from the allocator instead, so `global` is not compiled in: the atomic would otherwise be
//! contended by every thread on every allocation, and the thread-local buffering that makes it
//! affordable is inlined into every allocation site in the binary.
......
......@@ -14,7 +14,7 @@ To use the singleton pattern in turbo-tasks:
3. The [constructor arguments][TaskInput] act as a key for the constructor task which ensures that the same value is always celled in the same task.
4. Keep in mind that you should only compare `ResolvedVc`s by equality. Unresolved `Vc`s might not be equal to each other.
[value]: crate::value
[value]: macro@crate::value
[function]: crate::function
[TaskInput]: crate::TaskInput
......
......@@ -72,9 +72,9 @@ impl LocalTaskTracker {
/// Test-only: register an in-flight detached future (`spawn_detached_for_testing`). No
/// `LocalTask` slot is allocated; this just bumps the counter. Balanced by a matching
/// [`dec_in_flight`] when the wrapped future completes.
/// [`decrement_in_flight`] when the wrapped future completes.
///
/// [`dec_in_flight`]: LocalTaskTracker::dec_in_flight
/// [`decrement_in_flight`]: LocalTaskTracker::decrement_in_flight
pub(crate) fn register_detached(&mut self) {
self.in_flight += 1;
}
......
......@@ -210,7 +210,7 @@ pub trait TurboTasksApi: TurboTasksCallApi + Sync + Send {
fn mark_own_task_as_finished(&self, task: TaskId);
/// Pin a task against garbage collection. Delegates to
/// [`Backend::pin_task_for_gc`](crate::backend::Backend::pin_task_for_gc).
/// [`Backend::pin_task_for_gc`].
fn pin_task_for_gc(&self, task: TaskId);
/// Removes a pin added by [`pin_task_for_gc`](TurboTasksApi::pin_task_for_gc).
......@@ -573,7 +573,7 @@ pub struct InlineExecutionStats {
pub waited_in_progress: u64,
}
/// The counters behind [`InlineExecutionStats`].
/// The counters behind `InlineExecutionStats`.
///
/// Without the `inline_execution_stats` feature this is zero-sized and every method is an empty
/// `#[inline]` no-op, so the counting compiles away: the counters sit on the read-miss path, and a
......
......@@ -8,7 +8,7 @@
/// easy implementation on structs or enums.
///
/// This should eventually be replace by the `auto_traits`, once stabilized:
/// https://doc.rust-lang.org/nightly/unstable-book/language-features/auto-traits.html
/// <https://doc.rust-lang.org/nightly/unstable-book/language-features/auto-traits.html>
macro_rules! impl_auto_marker_trait {
($trait:ident) => {
$crate::marker_trait::impl_marker_trait!(
......
......@@ -33,7 +33,7 @@ impl<T> StateInner<T> {
}
/// Sets the value and returns the drained invalidators. The caller MUST
/// run them via [`run_invalidators`] *after* dropping the [`Mutex`] guard
/// run them via [`notify_mutated`] *after* dropping the [`Mutex`] guard
/// — calling [`Invalidator::invalidate`] may grab locks in the backend which can lead to cycles
#[must_use]
fn set_unconditionally(&mut self, value: T) -> AutoSet<Invalidator> {
......
......@@ -5,7 +5,7 @@ use unsize::Coercion;
/// Attempt to downcast a [`triomphe::Arc<dyn Any + Send +
/// Sync>`][`triomphe::Arc`] to a concrete type.
///
/// Checks that the downcast is safe using [`Any::is`].
/// Checks that the downcast is safe using [`Any::is`](https://doc.rust-lang.org/std/any/trait.Any.html#method.is).
///
/// Ported from [`std::sync::Arc::downcast`] to [`triomphe::Arc`].
pub fn downcast_triomphe_arc<T: Any + Send + Sync>(
......
......@@ -94,7 +94,7 @@ pub struct ValueType {
pub evictability: Evictability,
/// An implementation of
/// [`VcCellMode::raw_cell`][crate::vc::VcCellMode::raw_cell].
/// [`VcCellMode::raw_cell`].
///
/// Allows dynamically constructing a cell using the type id. Used inside of
/// [`TraitRef`][crate::TraitRef] where we have a type id, but not the concrete type `T` of
......@@ -146,7 +146,7 @@ impl ValueType {
/// Construct a `ValueType` for a non-codec persistence mode
/// ([`ValueTypePersistence::Skip`] / [`ValueTypePersistence::HashOnly`]).
///
/// Used by [`#[turbo_tasks::value]`][crate::value] for `serialization =
/// Used by [`#[turbo_tasks::value]`][macro@crate::value] for `serialization =
/// "skip"` and `serialization = "hash"`. For `serialization = "auto" |
/// "custom"` use [`ValueType::persistable`] instead — its codec functions
/// inline at the call site.
......@@ -161,7 +161,7 @@ impl ValueType {
/// Construct a `ValueType` whose cells round-trip through the persistent
/// cache via the auto-derived bincode `Encode` / `Decode` impls.
///
/// This is internally used by [`#[turbo_tasks::value]`][crate::value] for
/// This is internally used by [`#[turbo_tasks::value]`][macro@crate::value] for
/// `serialization = "auto"` and `serialization = "custom"`.
pub const fn persistable<T: VcValueType + Encode + Decode<()>>(
global_name: &'static str,
......
......@@ -727,7 +727,7 @@ pub struct ReadRawVcFuture {
/// Phase 1 and phase 2 of [`ReadRawVcFuture`] use disjoint sets of fields. Storing them in an
/// enum keeps the future smaller than holding both sets simultaneously.
enum ReadRawVcState {
/// Phase 1: resolves the [`RawVc`] pointer chain to a [`RawVc::TaskCell`].
/// Phase 1: resolves the [`RawVc`] pointer chain to a [`RawVcUnpacked::TaskCell`].
Resolving(ResolveRawVcFuture),
/// Phase 2: the resolved task/cell identity plus a listener for the cell read wait.
Reading {
......
......@@ -160,7 +160,9 @@ where
T: ?Sized,
Cast: VcCast,
{
/// Do not use this: Use [`OperationVc::read_strongly_consistent`] instead.
/// Do not use this: Use
/// [`OperationVc::read_strongly_consistent`](crate::OperationVc::read_strongly_consistent)
/// instead.
pub(crate) fn strongly_consistent(mut self) -> Self {
self.raw = self.raw.strongly_consistent();
self
......
......@@ -8,7 +8,7 @@ use crate::{
/// Custom traits for `VcValueType`s should be subtraits of [`VcValueTrait`].
///
/// You should not implement this trait directly, but instead use the
/// [`#[turbo_tasks::value]`][crate::value] macro instead.
/// [`#[turbo_tasks::value]`][macro@crate::value] macro instead.
///
/// ## Safety
///
......
......@@ -14,7 +14,7 @@ use petgraph::{
use rustc_hash::FxHashSet;
/// Read-only view over a directed weighted graph. Production code uses the `&DiGraph<N, u32>`
/// implementation; tests also use [`SubgraphView`] to exercise algorithms on filtered subsets.
/// implementation; tests also use `SubgraphView` to exercise algorithms on filtered subsets.
#[allow(dead_code)] // Some methods are kept for symmetry with the JS PoC; not all are used yet.
pub(super) trait ReadonlyGraph<'a>: Copy {
type NodesIter: Iterator<Item = NodeIndex>;
......
......@@ -158,7 +158,7 @@ impl Visitor<'_> for ModuleReferencesVisitor<'_> {
/// Noop. Urls in `@supports` are not used.
///
/// See https://github.com/vercel/next.js/issues/63102
/// See <https://github.com/vercel/next.js/issues/63102>
fn visit_supports_condition(
&mut self,
_: &mut lightningcss::rules::supports::SupportsCondition<'_>,
......
......@@ -81,7 +81,7 @@ pub(super) struct Analyzer<'arena, 'eval> {
pub(super) state: analyzer_state::AnalyzerState<'arena>,
pub(super) effects: BumpVec<'arena, Effect<'arena>>,
/// Effects collected from hoisted declarations. See https://developer.mozilla.org/en-US/docs/Glossary/Hoisting
/// Effects collected from hoisted declarations. See <https://developer.mozilla.org/en-US/docs/Glossary/Hoisting>
/// Tracked separately so we can preserve effects from hoisted declarations even when we don't
/// collect effects from the declaring context.
pub(super) hoisted_effects: BumpVec<'arena, Effect<'arena>>,
......@@ -809,7 +809,7 @@ pub fn as_parent_path_in<'a>(
path.into_boxed_slice()
}
/// Like [`as_parent_path_with`], but freezes the path into an arena-allocated boxed slice.
/// Like [`as_parent_path_in`], but appends `additional` to the frozen path.
pub fn as_parent_path_with_in<'a>(
arena: &'a Bump,
ast_path: &AstNodePath<AstParentNodeRef<'_>>,
......
......@@ -151,7 +151,7 @@ pub(crate) struct ItemData {
/// - Note: ImportBinding should depend on actual import statements because those imports may
/// have side effects.
///
/// See https://github.com/vercel/next.js/pull/71234#issuecomment-2409810084 for the problematic
/// See <https://github.com/vercel/next.js/pull/71234#issuecomment-2409810084> for the problematic
/// test case.
pub explicit_deps: Vec<ItemId>,
......
......@@ -112,7 +112,7 @@ impl EcmascriptAnalyzable for EcmascriptModulePartAsset {
#[turbo_tasks::value_impl]
impl EcmascriptModulePartAsset {
/// Create a new instance of [Vc<EcmascriptModulePartAsset>], which consists
/// Create a new instance of [`Vc<EcmascriptModulePartAsset>`], which consists
/// of a pointer to the full module and the [ModulePart] pointing the part
/// of the module.
#[turbo_tasks::function]
......
......@@ -19,7 +19,7 @@ const ROOT: u32 = 0;
/// The modifiers to run, indexed for a single downward walk of the AST.
pub struct Visitors<'a> {
/// Indexed by [`NodeId`]
/// Indexed by node id (`u32`)
/// Maps kinds to indices in children and modifiers
/// Traversal starts from `[ROOT]`
/// This structure is a little memory intensive but the visitors are short lived.
......
......@@ -94,9 +94,9 @@ const fn reserved_in_table(len: u32) -> u64 {
///
/// Precomputed rather than evaluated on the fly, because [`decode_js_identifier`] needs it for
/// every name it decodes and the formula costs a `pow` and a multiply.
/// [`capacity_for_len_matches_the_formula`] keeps the table honest. From `len == 11` the true value
/// exceeds `u64::MAX` (`54 * 64^10` alone is ≈ 6.2e19 against `u64::MAX`'s ≈ 1.8e19), so it
/// saturates there; no real export table comes anywhere near needing that many characters.
/// The `capacity_for_len_matches_the_formula` test keeps the table honest. From `len == 11` the
/// true value exceeds `u64::MAX` (`54 * 64^10` alone is ≈ 6.2e19 against `u64::MAX`'s ≈ 1.8e19), so
/// it saturates there; no real export table comes anywhere near needing that many characters.
fn capacity_for_len(len: u32) -> u64 {
CAPACITY_FOR_LEN
.get(len as usize)
......
......@@ -180,7 +180,7 @@ impl From<ImportMetaRef> for CodeGen {
}
/// URL encodes special chars that would appear in the "pathname" portion.
/// https://github.com/nodejs/node/blob/3bed5f11e039153eff5cbfd9513b8f55fd53fc43/lib/internal/url.js#L1513-L1526
/// <https://github.com/nodejs/node/blob/3bed5f11e039153eff5cbfd9513b8f55fd53fc43/lib/internal/url.js#L1513-L1526>
fn encode_path(path: &'_ str) -> Cow<'_, str> {
let mut encoded = String::new();
let mut start = 0;
......
......@@ -112,7 +112,7 @@ pub async fn read_tsconfigs(
}
/// Resolves tsconfig files according to TS's implementation:
/// https://github.com/microsoft/TypeScript/blob/611a912d/src/compiler/commandLineParser.ts#L3294-L3326
/// <https://github.com/microsoft/TypeScript/blob/611a912d/src/compiler/commandLineParser.ts#L3294-L3326>
#[tracing::instrument(skip_all)]
async fn resolve_extends(
tsconfig: Vc<Box<dyn Source>>,
......
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