docs(turbopack): Fix all warnings in cargo doc --no-deps --workspace, and run rustdoc as part of our CI checks

Author: bgw

crates/next-napi-bindings/src/next_api/utils.rs

@@ -98,6 +98,12 @@ pub fn root_task_dispose(
     Ok(())
 }
 
+/// [Peeks] at the [`Issue`] held by the given source and returns it as a [`PlainDiagnostic`].
+/// It does not [consume] any [`Issue`]s held by the source.
+///
+/// [Peeks]: turbo_tasks::CollectiblesSource::peek_collectibles
+/// [`Issue`]: turbopack_core::issue::Issue
+/// [consume]: turbo_tasks::CollectiblesSource::take_collectibles
 pub async fn get_issues<T: Send>(
     source: OperationVc<T>,
     filter: Vc<IssueFilter>,
@@ -107,10 +113,11 @@ pub async fn get_issues<T: Send>(
     ))
 }
 
-/// Reads the [turbopack_core::diagnostics::Diagnostic] held
-/// by the given source and returns it as a
-/// [turbopack_core::diagnostics::PlainDiagnostic]. It does
-/// not consume any Diagnostics held by the source.
+/// [Peeks] at the [`Diagnostic`]s held by the given source and returns it as a [`PlainDiagnostic`].
+/// It does not [consume] any [`Diagnostic`]s held by the source.
+///
+/// [Peeks]: turbo_tasks::CollectiblesSource::peek_collectibles
+/// [consume]: turbo_tasks::CollectiblesSource::take_collectibles
 pub async fn get_diagnostics<T: Send>(
     source: OperationVc<T>,
 ) -> Result<Arc<Vec<ReadRef<PlainDiagnostic>>>> {

crates/next-taskless/src/constants.rs

@@ -70,10 +70,13 @@ pub const NODE_EXTERNALS: [&str; 68] = [
     "zlib",
 ];
 
-/// List of node.js internals that are supported by edge runtime.
-/// If anything Node.js builtin module apart from these these imports are
-/// used and user does not provide alias for the polyfill, a runtime error will be thrown.
-/// See https://vercel.com/docs/functions/runtimes/edge-runtime#compatible-node.js-modules
+/// The Node.js built-in modules that are supported by edge runtime.
+///
+/// If any Node.js builtin module apart from these these imports are used and the user does not
+/// provide an alias for it (i.e. a polyfill), a runtime error will be thrown.
+///
+/// See <https://vercel.com/docs/functions/runtimes/edge-runtime#compatible-node.js-modules>
+//
 // SAFETY: This has to be sorted alphabetically since we are doing binary search on it
 pub const EDGE_NODE_EXTERNALS: [&str; 7] = [
     "assert",

packages/next-swc/package.json

@@ -16,8 +16,9 @@
     "build-native-wasi": "npx --package=@napi-rs/cli@3.0.0-alpha.45 napi build --platform --target wasm32-wasip1-threads -p next-napi-bindings --cwd ../../ --output-dir packages/next-swc/native --no-default-features",
     "build-wasm": "wasm-pack build ../../crates/wasm --scope=next",
     "cache-build-native": "[ -d native ] && echo $(ls native)",
-    "rust-check-fmt": "cd ../..; cargo fmt -- --check",
     "rust-check-clippy": "cargo clippy --workspace --all-targets -- -D warnings -A deprecated",
+    "rust-check-doc": "RUSTDOCFLAGS='-Zunstable-options --output-format=json' cargo doc --no-deps --workspace",
+    "rust-check-fmt": "cd ../..; cargo fmt -- --check",
     "rust-check-napi": "cargo check -p next-napi-bindings",
     "test-cargo-unit": "cargo nextest run --workspace --exclude next-napi-bindings --exclude turbo-tasks-macros --cargo-profile release-with-assertions --no-fail-fast"
   },

packages/next-swc/turbo.jsonc

@@ -136,9 +136,14 @@
       "outputs": ["native/*.node", "native/index.d.ts"],
     },
     "rust-check": {
-      "dependsOn": ["rust-check-fmt", "rust-check-clippy", "rust-check-napi"],
+      "dependsOn": [
+        "rust-check-clippy",
+        "rust-check-doc",
+        "rust-check-fmt",
+        "rust-check-napi",
+      ],
     },
-    "rust-check-fmt": {
+    "rust-check-clippy": {
       "inputs": [
         "../../.cargo/**",
         "../../crates/**",
@@ -148,9 +153,8 @@
         "../../.github/workflows/build_and_deploy.yml",
         "../../rust-toolchain.toml",
       ],
-      "cache": false,
     },
-    "rust-check-clippy": {
+    "rust-check-doc": {
       "inputs": [
         "../../.cargo/**",
         "../../crates/**",
@@ -161,6 +165,18 @@
         "../../rust-toolchain.toml",
       ],
     },
+    "rust-check-fmt": {
+      "inputs": [
+        "../../.cargo/**",
+        "../../crates/**",
+        "../../turbopack/crates/**",
+        "../../**/Cargo.toml",
+        "../../**/Cargo.lock",
+        "../../.github/workflows/build_and_deploy.yml",
+        "../../rust-toolchain.toml",
+      ],
+      "cache": false,
+    },
     "rust-check-napi": {
       "inputs": [
         "../../.cargo/**",

turbopack/crates/turbo-tasks-backend/src/backing_storage.rs

@@ -37,13 +37,12 @@ pub trait BackingStorage: BackingStorageSealed {
     ///
     /// This typically means that we'll restart the process or `turbo-tasks` soon with a fresh
     /// database. If this happens, there's no point in writing anything else to disk, or flushing
-    /// during [`KeyValueDatabase::shutdown`].
+    /// during [`TurboTasksBackend::stop`].
     ///
-    /// This can be implemented by calling [`invalidate_db`] with
-    /// the database's non-versioned base path.
-    ///
-    /// [`KeyValueDatabase::shutdown`]: crate::database::key_value_database::KeyValueDatabase::shutdown
-    /// [`invalidate_db`]: crate::database::db_invalidation::invalidate_db
+    /// [`TurboTasksBackend::stop`]: turbo_tasks::backend::Backend::stop
+    //
+    // This can be implemented by calling `database::db_invalidation::invalidate_db` with the
+    // database's non-versioned base path.
     fn invalidate(&self, reason_code: &str) -> Result<()>;
 }
 

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

@@ -48,9 +48,10 @@ impl Deref for Bytes {
     }
 }
 
-/// Types that implement From<X> for Bytes {}
-/// Unfortunately, we cannot just use the more generic `Into<Bytes>` without
-/// running afoul of the `From<X> for X` base case, causing conflicting impls.
+/// Types that `impl From<CustomType> for Bytes {}`
+///
+/// Unfortunately, we cannot just use the more generic `Into<Bytes>` without running afoul of the
+/// `From<X> for X` base case, causing conflicting impls.
 pub trait IntoBytes: Into<CBytes> {}
 impl IntoBytes for &'static [u8] {}
 impl IntoBytes for &'static str {}

turbopack/crates/turbo-tasks-fs/src/embed/dir.rs

@@ -25,17 +25,17 @@ pub fn directory_from_include_dir(
     Vc::upcast(EmbeddedFileSystem::new(name, dir))
 }
 
-/// Returns an embedded [Vc<Box<dyn FileSystem>>] for the given path.
+/// Returns an embedded [`Vc<Box<dyn FileSystem>>`][FileSystem] for the given path.
 ///
-/// This will embed a directory's content into the binary and
-/// create an [Vc<EmbeddedFileSystem>].
+/// This will embed a directory's content into the binary and create an
+/// [`Vc<EmbeddedFileSystem>`][EmbeddedFileSystem].
 ///
-/// If you enable the `dynamic_embed_contents` feature, calling
-/// the macro will return a [Vc<DiskFileSystem>].
+/// If you enable the `dynamic_embed_contents` feature, calling the macro will return a
+/// [`Vc<DiskFileSystem>`][DiskFileSystem].
 ///
-/// This enables dynamic linking (and hot reloading) of embedded files/dirs.
-/// A binary built with `dynamic_embed_contents` enabled is **is not portable**,
-/// only the directory path will be embedded into the binary.
+/// This enables dynamic linking (and hot reloading) of embedded files/dirs. A binary built with
+/// `dynamic_embed_contents` enabled is **is not portable**, only the directory path will be
+/// embedded into the binary.
 #[macro_export]
 macro_rules! embed_directory {
     ($name:tt, $path:tt) => {{        // make sure the path contains `$CARGO_MANIFEST_DIR`

turbopack/crates/turbo-tasks-fs/src/lib.rs

@@ -91,19 +91,6 @@ use crate::{
 };
 pub use crate::{read_glob::ReadGlobResult, virtual_fs::VirtualFileSystem};
 
-/// A (somewhat arbitrary) filename limit that we should try to keep output file names below.
-///
-/// For the sake of consistency, this is a fixed constant that is likely to be safe across all
-/// platforms.
-///
-/// Different operating systems have different limits on file name and file path. See
-/// [`validate_path_length`] for details. Because this only accounts for a single path segment, and
-/// not the total path length, this cannot not guarantee a full file path is safe.
-///
-/// To ensure file names are kept within this limit, call
-/// [`FileSystemPath::truncate_file_name_with_hash`].
-pub const MAX_SAFE_FILE_NAME_LENGTH: usize = 200;
-
 /// Validate the path, returning the valid path, a modified-but-now-valid path, or bailing with an
 /// error.
 ///
@@ -1553,9 +1540,8 @@ impl FileSystemPath {
         FileSystemPath { fs, path }
     }
 
-    /// Adds a subpath to the current path. The /-separate path argument might
-    /// contain ".." or "." segments, but it must not leave the root of the
-    /// filesystem.
+    /// Adds a subpath to the current path. The /-separated `path` argument might contain ".." or
+    /// "." segments, but it must not leave the root of the filesystem.
     pub fn join(&self, path: &str) -> Result<Self> {
         if let Some(path) = join_path(&self.path, path) {
             Ok(Self::new_normalized(self.fs, path.into()))
@@ -1568,7 +1554,7 @@ impl FileSystemPath {
         }
     }
 
-    /// Adds a suffix to the filename. [path] must not contain `/`.
+    /// Adds a suffix to the filename. `path` must not contain `/`.
     pub fn append(&self, path: &str) -> Result<Self> {
         if path.contains('/') {
             bail!(
@@ -1583,12 +1569,12 @@ impl FileSystemPath {
         ))
     }
 
-    /// Adds a suffix to the basename of the filename. [appending] must not
-    /// contain `/`. Extension will stay intact.
+    /// Adds a suffix to the basename of the file path. `appending` must not contain `/`. The [file
+    /// extension][FileSystemPath::extension] will stay intact.
     pub fn append_to_stem(&self, appending: &str) -> Result<Self> {
         if appending.contains('/') {
             bail!(
-                "FileSystemPath(\"{}\").append_to_stem(\"{}\") must not append '/'",
+                "FileSystemPath({:?}).append_to_stem({:?}) must not append '/'",
                 self.path,
                 appending,
             )
@@ -1628,14 +1614,15 @@ impl FileSystemPath {
         None
     }
 
-    /// DETERMINISM: Result is in random order. Either sort result or do not depend
-    /// on the order.
+    /// DETERMINISM: Result is in random order. Either sort the result or do not depend on the
+    /// order.
     pub fn read_glob(&self, glob: Vc<Glob>) -> Vc<ReadGlobResult> {
         read_glob(self.clone(), glob)
     }
 
-    // Tracks all files and directories matching the glob
-    // Follows symlinks as though they were part of the original hierarchy.
+    // Tracks all files and directories matching the glob using the filesystem watcher. Follows
+    // symlinks as though they were part of the original hierarchy. The returned [`Vc`] will be
+    // invalidated if a file or directory changes.
     pub fn track_glob(&self, glob: Vc<Glob>, include_dot_files: bool) -> Vc<Completion> {
         track_glob(self.clone(), glob, include_dot_files)
     }
@@ -2046,7 +2033,7 @@ pub enum LinkContent {
     ///
     /// We don't use the [`FileSystemPath`] to store the target, because the [`FileSystemPath`] is
     /// always normalized. In [`FileSystemPath::write_symbolic_link_dir`] we need to compare
-    /// `target` with the value returned by [`sys::fs::read_link`].
+    /// `target` with the value returned by [`std::fs::read_link`].
     Link {
         target: RcStr,
         link_type: LinkType,

turbopack/crates/turbo-tasks-fs/src/rope.rs

@@ -159,8 +159,8 @@ impl<T: Into<Bytes>> From<T> for Rope {
 impl RopeBuilder {
     /// Push owned bytes into the Rope.
     ///
-    /// If possible use [push_static_bytes] or `+=` operation instead, as they
-    /// will create a reference to shared memory instead of cloning the bytes.
+    /// If possible, use [`RopeBuilder::push_static_bytes`] or `+=` operation instead. That will
+    /// create a reference to shared memory instead of cloning the bytes.
     pub fn push_bytes(&mut self, bytes: &[u8]) {
         if bytes.is_empty() {
             return;
@@ -414,7 +414,7 @@ impl DeterministicHash for RopeBytesOnlyHash<'_> {
 /// [`Rope::to_bytes`] instead would be easier, but would require copying to an intermediate buffer.
 ///
 /// This len + bytes format is similar to how bincode would normally encode a `&[u8]`:
-/// https://docs.rs/bincode/latest/bincode/spec/index.html#collections
+/// <https://docs.rs/bincode/latest/bincode/spec/index.html#collections>
 impl Encode for Rope {
     fn encode<E: Encoder>(&self, encoder: &mut E) -> Result<(), EncodeError> {
         self.length.encode(encoder)?;
@@ -882,7 +882,7 @@ impl BufRead for RopeReader<'_> {
 }
 
 impl<'a> Stream for RopeReader<'a> {
-    /// This is efficiently streamable into a [`Hyper::Body`] if each item is cloned into an owned
+    /// This is efficiently streamable into a `Hyper::Body` if each item is cloned into an owned
     /// `Bytes` instance.
     type Item = Result<&'a Bytes>;
 

turbopack/crates/turbo-tasks-fs/src/util.rs

@@ -8,9 +8,9 @@ use turbo_tasks::ResolvedVc;
 
 use crate::{DiskFileSystem, FileSystemPath};
 
-/// Converts a disk access Result<T> into a Result<Some<T>>, where a NotFound
-/// error results in a None value. This is purely to reduce boilerplate code
-/// comparing NotFound errors against all other errors.
+/// Converts a disk access `Result<T>` into a `Result<Some<T>>`, where a [`ErrorKind::NotFound`] (or
+/// [`ErrorKind::InvalidFilename`]) error results in a [`None`] value. This is purely to reduce
+/// boilerplate code comparing [`ErrorKind::NotFound`] errors against all other errors.
 pub fn extract_disk_access<T>(value: io::Result<T>, path: &Path) -> Result<Option<T>> {
     match value {
         Ok(v) => Ok(Some(v)),