docs: Fix inter-crate doc links (#10562)

This commit is contained in:
Andy Leiserson authored and GitHub committed 2026-10-13 18:39:07 +00:00
1 parent 20a17523e2
commit 0caefd83a2
3 files changed
+101 -102

No files matched your search

-100
View File
@@ -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))]
+100 -1
View File
@@ -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.
///
+1 -1
View File
@@ -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.
///