From 0caefd83a2c438334ba78b73ab4f41702178d9a9 Mon Sep 17 00:00:00 2001 From: Andy Leiserson Date: Tue, 13 Oct 2026 11:39:07 -0700 Subject: [PATCH] docs: Fix inter-crate doc links (#10562) --- naga-types/src/lib.rs | 100 -------------------------------------- wgpu-types/src/lib.rs | 101 ++++++++++++++++++++++++++++++++++++++- wgpu-types/src/limits.rs | 2 +- 3 files changed, 101 insertions(+), 102 deletions(-) diff --git a/naga-types/src/lib.rs b/naga-types/src/lib.rs index ff0311a30..293448bf2 100644 --- a/naga-types/src/lib.rs +++ b/naga-types/src/lib.rs @@ -10,106 +10,6 @@ pub mod msl; pub mod spv; pub mod wgsl; -/// Create a Markdown link definition referring to the `wgpu` crate. -/// -/// This macro should be used inside a `#[doc = ...]` attribute. -/// The two arguments should be string literals or macros that expand to string literals. -/// If the module in which the item using this macro is located is not the crate root, -/// use the `../` syntax. -/// -/// We cannot simply use rustdoc links to `wgpu` because it is one of our dependents. -/// This link adapts to work in locally generated documentation (`cargo doc`) by default, -/// and work with `docs.rs` URL structure when building for `docs.rs`. -/// -/// Note: This macro cannot be used outside this crate, because `cfg(docsrs)` will not apply. -#[cfg(not(docsrs))] -#[macro_export] -macro_rules! link_to_wgpu_docs { - ([$reference:expr]: $url_path:expr) => { - concat!("[", $reference, "]: ../wgpu/", $url_path) - }; - - (../ [$reference:expr]: $url_path:expr) => { - concat!("[", $reference, "]: ../../wgpu/", $url_path) - }; -} -#[cfg(docsrs)] -#[macro_export] -macro_rules! link_to_wgpu_docs { - ($(../)? [$reference:expr]: $url_path:expr) => { - concat!( - "[", - $reference, - // URL path will have a base URL of https://docs.rs/ - "]: /wgpu/", - // The version of wgpu-types is not necessarily the same as the version of wgpu - // if a patch release of either has been published, so we cannot use the full version - // number. docs.rs will interpret this single number as a Cargo-style version - // requirement and redirect to the latest compatible version. - // - // This technique would break if `wgpu` and `wgpu-types` ever switch to having distinct - // major version numbering. An alternative would be to hardcode the corresponding `wgpu` - // version, but that would give us another thing to forget to update. - env!("CARGO_PKG_VERSION_MAJOR"), - "/wgpu/", - $url_path - ) - }; -} - -/// Create a Markdown link definition referring to an item in the `wgpu` crate. -/// -/// This macro should be used inside a `#[doc = ...]` attribute. -/// See [`link_to_wgpu_docs`] for more details. -#[macro_export] -macro_rules! link_to_wgpu_item { - ($kind:ident $name:ident) => { - $crate::link_to_wgpu_docs!( - [concat!("`", stringify!($name), "`")]: concat!(stringify!($kind), ".", stringify!($name), ".html") - ) - }; -} - -/// Create a Markdown link definition referring to the `wgpu_core` crate. -/// -/// This macro should be used inside a `#[doc = ...]` attribute. -/// See [`link_to_wgpu_docs`] for more details. -#[cfg(not(docsrs))] -#[macro_export] -macro_rules! link_to_wgc_docs { - ([$reference:expr]: $url_path:expr) => { - concat!("[", $reference, "]: ../wgpu_core/", $url_path) - }; - - (../ [$reference:expr]: $url_path:expr) => { - concat!("[", $reference, "]: ../../wgpu_core/", $url_path) - }; -} -#[cfg(docsrs)] -#[macro_export] -macro_rules! link_to_wgc_docs { - ($(../)? [$reference:expr]: $url_path:expr) => { - concat!( - "[", - $reference, - // URL path will have a base URL of https://docs.rs/ - "]: /wgpu_core/", - // The version of wgpu-types is not necessarily the same as the version of wgpu_core - // if a patch release of either has been published, so we cannot use the full version - // number. docs.rs will interpret this single number as a Cargo-style version - // requirement and redirect to the latest compatible version. - // - // This technique would break if `wgpu_core` and `wgpu-types` ever switch to having - // distinct major version numbering. An alternative would be to hardcode the - // corresponding `wgpu_core` version, but that would give us another thing to forget - // to update. - env!("CARGO_PKG_VERSION_MAJOR"), - "/wgpu_core/", - $url_path - ) - }; -} - /// Stage of the programmable pipeline. #[derive(Clone, Copy, Debug, Hash, Eq, Ord, PartialEq, PartialOrd)] #[cfg_attr(feature = "serialize", derive(serde::Serialize))] diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs index 26a75ccb0..79e3e6813 100644 --- a/wgpu-types/src/lib.rs +++ b/wgpu-types/src/lib.rs @@ -86,7 +86,106 @@ pub use write_only::*; pub(crate) use bitflags_array::*; pub(crate) use macros::ConstDefault; -pub(crate) use naga_types::{link_to_wgc_docs, link_to_wgpu_docs, link_to_wgpu_item}; + +/// Create a Markdown link definition referring to the `wgpu` crate. +/// +/// This macro should be used inside a `#[doc = ...]` attribute. +/// The two arguments should be string literals or macros that expand to string literals. +/// If the module in which the item using this macro is located is not the crate root, +/// use the `../` syntax. +/// +/// We cannot simply use rustdoc links to `wgpu` because it is one of our dependents. +/// This link adapts to work in locally generated documentation (`cargo doc`) by default, +/// and work with `docs.rs` URL structure when building for `docs.rs`. +/// +/// Note: This macro cannot be used outside this crate, because `cfg(docsrs)` will not apply. +#[cfg(not(docsrs))] +#[macro_export] +macro_rules! link_to_wgpu_docs { + ([$reference:expr]: $url_path:expr) => { + concat!("[", $reference, "]: ../wgpu/", $url_path) + }; + + (../ [$reference:expr]: $url_path:expr) => { + concat!("[", $reference, "]: ../../wgpu/", $url_path) + }; +} +#[cfg(docsrs)] +#[macro_export] +macro_rules! link_to_wgpu_docs { + ($(../)? [$reference:expr]: $url_path:expr) => { + concat!( + "[", + $reference, + // URL path will have a base URL of https://docs.rs/ + "]: /wgpu/", + // The version of wgpu-types is not necessarily the same as the version of wgpu + // if a patch release of either has been published, so we cannot use the full version + // number. docs.rs will interpret this single number as a Cargo-style version + // requirement and redirect to the latest compatible version. + // + // This technique would break if `wgpu` and `wgpu-types` ever switch to having distinct + // major version numbering. An alternative would be to hardcode the corresponding `wgpu` + // version, but that would give us another thing to forget to update. + env!("CARGO_PKG_VERSION_MAJOR"), + "/wgpu/", + $url_path + ) + }; +} + +/// Create a Markdown link definition referring to an item in the `wgpu` crate. +/// +/// This macro should be used inside a `#[doc = ...]` attribute. +/// See [`link_to_wgpu_docs`] for more details. +#[macro_export] +macro_rules! link_to_wgpu_item { + ($kind:ident $name:ident) => { + $crate::link_to_wgpu_docs!( + [concat!("`", stringify!($name), "`")]: concat!(stringify!($kind), ".", stringify!($name), ".html") + ) + }; +} + +/// Create a Markdown link definition referring to the `wgpu_core` crate. +/// +/// This macro should be used inside a `#[doc = ...]` attribute. +/// See [`link_to_wgpu_docs`] for more details. +#[cfg(not(docsrs))] +#[macro_export] +macro_rules! link_to_wgc_docs { + ([$reference:expr]: $url_path:expr) => { + concat!("[", $reference, "]: ../wgpu_core/", $url_path) + }; + + (../ [$reference:expr]: $url_path:expr) => { + concat!("[", $reference, "]: ../../wgpu_core/", $url_path) + }; +} +#[cfg(docsrs)] +#[macro_export] +macro_rules! link_to_wgc_docs { + ($(../)? [$reference:expr]: $url_path:expr) => { + concat!( + "[", + $reference, + // URL path will have a base URL of https://docs.rs/ + "]: /wgpu_core/", + // The version of wgpu-types is not necessarily the same as the version of wgpu_core + // if a patch release of either has been published, so we cannot use the full version + // number. docs.rs will interpret this single number as a Cargo-style version + // requirement and redirect to the latest compatible version. + // + // This technique would break if `wgpu_core` and `wgpu-types` ever switch to having + // distinct major version numbering. An alternative would be to hardcode the + // corresponding `wgpu_core` version, but that would give us another thing to forget + // to update. + env!("CARGO_PKG_VERSION_MAJOR"), + "/wgpu_core/", + $url_path + ) + }; +} /// Integral type used for [`Buffer`] offsets and sizes. /// diff --git a/wgpu-types/src/limits.rs b/wgpu-types/src/limits.rs index 0b33cbf97..3eb1680b7 100644 --- a/wgpu-types/src/limits.rs +++ b/wgpu-types/src/limits.rs @@ -8,7 +8,7 @@ use serde::{Deserialize, Serialize}; #[cfg(doc)] use crate::{Features, TextureFormat}; -use naga_types::link_to_wgpu_item; +use crate::link_to_wgpu_item; /// Invoke a macro for each of the limits. ///