[doc] Render toolchain version detection in rustdoc

Previously, we had avoided doing this because there wasn't any way to guarantee that we didn't make mistakes and render the wrong version for a particular named toolchain version. In this commit, we take the pragmatic approach of renaming the named toolchain versions - in particular, we add a suffix which includes the toolchain version. This is fairly error-resistant for two reasons: - At the definition site (in `Cargo.toml`), the name appears on the same line as the version, so mistakes should be obvious - At the use site (in various `.rs` files), the name appears within a few lines of any `#[cfg_attr(doc_cfg, doc(cfg(...)))]` attribute, so mistakes should similarly be obvious Closes #894 gherrit-pr-id: I74b8e9be0e6cb6e02552d2e1f985b490a7d37afe
google · Oct 18, 2024 · 2934c82 · 2934c82
1 parent 40947c6
commit 2934c82
Show file tree

Hide file tree

Showing 9 changed files with 121 additions and 111 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -54,12 +54,12 @@ jobs:
           # These are the names of specific Rust versions detected in
           # `build.rs`. Each of these represents the minimum Rust version for
           # which a particular feature is supported.
-          "zerocopy-core-error",
-          "zerocopy-diagnostic-on-unimplemented",
-          "zerocopy-generic-bounds-in-const-fn",
-          "zerocopy-target-has-atomics",
-          "zerocopy-aarch64-simd",
-          "zerocopy-panic-in-const-and-vec-try-reserve"
+          "zerocopy-core-error-1-81-0",
+          "zerocopy-diagnostic-on-unimplemented-1-78-0",
+          "zerocopy-generic-bounds-in-const-fn-1-61-0",
+          "zerocopy-target-has-atomics-1-60-0",
+          "zerocopy-aarch64-simd-1-59-0",
+          "zerocopy-panic-in-const-and-vec-try-reserve-1-57-0"
         ]
         target: [
           "i686-unknown-linux-gnu",
@@ -89,17 +89,17 @@ jobs:
             features: "--all-features"
           - toolchain: "stable"
             features: "--all-features"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             features: "--all-features"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             features: "--all-features"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             features: "--all-features"
-          - toolchain: "zerocopy-target-has-atomics"
+          - toolchain: "zerocopy-target-has-atomics-1-60-0"
             features: "--all-features"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             features: "--all-features"
-          - toolchain: "zerocopy-panic-in-const-and-vec-try-reserve"
+          - toolchain: "zerocopy-panic-in-const-and-vec-try-reserve-1-57-0"
             features: "--all-features"
           # Exclude any combination for the zerocopy-derive crate which
           # uses zerocopy features.
@@ -114,103 +114,103 @@ jobs:
           # exist to exercise zerocopy behavior which differs by toolchain;
           # zerocopy-derive doesn't behave different on these toolchains.
           - crate: "zerocopy-derive"
-            toolchain: "zerocopy-core-error"
+            toolchain: "zerocopy-core-error-1-81-0"
           - crate: "zerocopy-derive"
-            toolchain: "zerocopy-diagnostic-on-unimplemented"
+            toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
           - crate: "zerocopy-derive"
-            toolchain: "zerocopy-generic-bounds-in-const-fn"
+            toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
           - crate: "zerocopy-derive"
-            toolchain: "zerocopy-target-has-atomics"
+            toolchain: "zerocopy-target-has-atomics-1-60-0"
           - crate: "zerocopy-derive"
-            toolchain: "zerocopy-aarch64-simd"
+            toolchain: "zerocopy-aarch64-simd-1-59-0"
           - crate: "zerocopy-derive"
-            toolchain: "zerocopy-panic-in-const-and-vec-try-reserve"
-          # Exclude non-aarch64 targets from the `zerocopy-aarch64-simd`
+            toolchain: "zerocopy-panic-in-const-and-vec-try-reserve-1-57-0"
+          # Exclude non-aarch64 targets from the `zerocopy-aarch64-simd-1-59-0`
           # toolchain.
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "i686-unknown-linux-gnu"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "x86_64-unknown-linux-gnu"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "arm-unknown-linux-gnueabi"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "powerpc-unknown-linux-gnu"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "powerpc64-unknown-linux-gnu"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "riscv64gc-unknown-linux-gnu"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "s390x-unknown-linux-gnu"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "x86_64-pc-windows-msvc"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "thumbv6m-none-eabi"
-          - toolchain: "zerocopy-aarch64-simd"
+          - toolchain: "zerocopy-aarch64-simd-1-59-0"
             target: "wasm32-wasi"
-          # Exclude most targets targets from the `zerocopy-core-error`
-          # toolchain since the `zerocopy-core-error` feature is unrelated to
+          # Exclude most targets targets from the `zerocopy-core-error-1-81-0`
+          # toolchain since the `zerocopy-core-error-1-81-0` feature is unrelated to
           # compilation target. This only leaves i686 and x86_64 targets.
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "arm-unknown-linux-gnueabi"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "aarch64-unknown-linux-gnu"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "powerpc-unknown-linux-gnu"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "powerpc64-unknown-linux-gnu"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "riscv64gc-unknown-linux-gnu"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "s390x-unknown-linux-gnu"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "x86_64-pc-windows-msvc"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "thumbv6m-none-eabi"
-          - toolchain: "zerocopy-core-error"
+          - toolchain: "zerocopy-core-error-1-81-0"
             target: "wasm32-wasi"
           # Exclude most targets targets from the
-          # `zerocopy-diagnostic-on-unimplemented` toolchain since the
-          # `zerocopy-diagnostic-on-unimplemented` feature is unrelated to
+          # `zerocopy-diagnostic-on-unimplemented-1-78-0` toolchain since the
+          # `zerocopy-diagnostic-on-unimplemented-1-78-0` feature is unrelated to
           # compilation target. This only leaves i686 and x86_64 targets.
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "arm-unknown-linux-gnueabi"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "aarch64-unknown-linux-gnu"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "powerpc-unknown-linux-gnu"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "powerpc64-unknown-linux-gnu"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "riscv64gc-unknown-linux-gnu"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "s390x-unknown-linux-gnu"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "x86_64-pc-windows-msvc"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "thumbv6m-none-eabi"
-          - toolchain: "zerocopy-diagnostic-on-unimplemented"
+          - toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
             target: "wasm32-wasi"
           # Exclude most targets targets from the
-          # `zerocopy-generic-bounds-in-const-fn` toolchain since the
-          # `zerocopy-generic-bounds-in-const-fn` feature is unrelated to
+          # `zerocopy-generic-bounds-in-const-fn-1-61-0` toolchain since the
+          # `zerocopy-generic-bounds-in-const-fn-1-61-0` feature is unrelated to
           # compilation target. This only leaves i686 and x86_64 targets.
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "arm-unknown-linux-gnueabi"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "aarch64-unknown-linux-gnu"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "powerpc-unknown-linux-gnu"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "powerpc64-unknown-linux-gnu"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "riscv64gc-unknown-linux-gnu"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "s390x-unknown-linux-gnu"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "x86_64-pc-windows-msvc"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "thumbv6m-none-eabi"
-          - toolchain: "zerocopy-generic-bounds-in-const-fn"
+          - toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
             target: "wasm32-wasi"
           # Exclude `thumbv6m-none-eabi` combined with any feature that implies
           # the `std` feature since `thumbv6m-none-eabi` does not include a

diff --git a/Cargo.toml b/Cargo.toml
@@ -31,27 +31,31 @@ exclude = [".*"]
 # which will be emitted if zerocopy is built with a toolchain version at least
 # as high as the specified version. In the emitted `--cfg`, dashes are replaced
 # by underscores.
+#
+# Each name is suffixed with the version it corresponds to. This is a convention
+# used in the codebase to make it less likely for us to make mistakes when
+# writing `doc_cfg` attributes.
 
 # From 1.81.0, Rust supports the `core::error::Error` trait.
-zerocopy-core-error = "1.81.0"
+zerocopy-core-error-1-81-0 = "1.81.0"
 
 # From 1.78.0, Rust supports the `#[diagnostic::on_unimplemented]` attribute.
-zerocopy-diagnostic-on-unimplemented = "1.78.0"
+zerocopy-diagnostic-on-unimplemented-1-78-0 = "1.78.0"
 
 # From 1.61.0, Rust supports generic types with trait bounds in `const fn`.
-zerocopy-generic-bounds-in-const-fn = "1.61.0"
+zerocopy-generic-bounds-in-const-fn-1-61-0 = "1.61.0"
 
 # From 1.60.0, Rust supports `cfg(target_has_atomics)`, which allows us to
 # detect whether a target supports particular sets of atomics.
-zerocopy-target-has-atomics = "1.60.0"
+zerocopy-target-has-atomics-1-60-0 = "1.60.0"
 
 # When the "simd" feature is enabled, include SIMD types from the
 # `core::arch::aarch64` module, which was stabilized in 1.59.0. On earlier Rust
 # versions, these types require the "simd-nightly" feature.
-zerocopy-aarch64-simd = "1.59.0"
+zerocopy-aarch64-simd-1-59-0 = "1.59.0"
 
 # Permit panicking in `const fn`s and calling `Vec::try_reserve`.
-zerocopy-panic-in-const-and-vec-try-reserve = "1.57.0"
+zerocopy-panic-in-const-and-vec-try-reserve-1-57-0 = "1.57.0"
 
 [package.metadata.ci]
 # The versions of the stable and nightly compiler toolchains to use in CI.

diff --git a/src/error.rs b/src/error.rs
@@ -121,9 +121,9 @@ use core::{
     ops::Deref,
 };
 
-#[cfg(zerocopy_core_error)]
+#[cfg(zerocopy_core_error_1_81_0)]
 use core::error::Error;
-#[cfg(all(not(zerocopy_core_error), any(feature = "std", test)))]
+#[cfg(all(not(zerocopy_core_error_1_81_0), any(feature = "std", test)))]
 use std::error::Error;
 
 use crate::{util::SendSyncPhantomData, KnownLayout, TryFromBytes, Unaligned};
@@ -232,7 +232,8 @@ impl<A: fmt::Display, S: fmt::Display, V: fmt::Display> fmt::Display for Convert
     }
 }
 
-#[cfg(any(zerocopy_core_error, feature = "std", test))]
+#[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
+#[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
 impl<A, S, V> Error for ConvertError<A, S, V>
 where
     A: fmt::Display + fmt::Debug,
@@ -389,7 +390,8 @@ where
     }
 }
 
-#[cfg(any(zerocopy_core_error, feature = "std", test))]
+#[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
+#[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
 impl<Src, Dst: ?Sized> Error for AlignmentError<Src, Dst>
 where
     Src: Deref,
@@ -534,7 +536,8 @@ where
     }
 }
 
-#[cfg(any(zerocopy_core_error, feature = "std", test))]
+#[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
+#[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
 impl<Src, Dst: ?Sized> Error for SizeError<Src, Dst>
 where
     Src: Deref,
@@ -641,7 +644,8 @@ where
     }
 }
 
-#[cfg(any(zerocopy_core_error, feature = "std", test))]
+#[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
+#[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
 impl<Src, Dst: ?Sized> Error for ValidityError<Src, Dst>
 where
     Src: Deref,

diff --git a/src/impls.rs b/src/impls.rs
@@ -442,7 +442,7 @@ safety_comment! {
 }
 
 #[cfg(all(
-    zerocopy_target_has_atomics,
+    zerocopy_target_has_atomics_1_60_0,
     any(
         target_has_atomic = "8",
         target_has_atomic = "16",
@@ -451,6 +451,7 @@ safety_comment! {
         target_has_atomic = "ptr"
     )
 ))]
+#[cfg_attr(doc_cfg, doc(cfg(rust = "1.60.0")))]
 mod atomics {
     use super::*;
 
@@ -933,7 +934,8 @@ mod simd {
             #[cfg(all(feature = "simd-nightly", target_arch = "powerpc64"))]
             powerpc64, powerpc64, vector_bool_long, vector_double, vector_signed_long, vector_unsigned_long
         );
-        #[cfg(zerocopy_aarch64_simd)]
+        #[cfg(zerocopy_aarch64_simd_1_59_0)]
+        #[cfg_attr(doc_cfg, doc(cfg(rust = "1.59.0")))]
         simd_arch_mod!(
             // NOTE(https://github.com/rust-lang/stdarch/issues/1484): NEON intrinsics are currently
             // broken on big-endian platforms.
@@ -1882,7 +1884,7 @@ mod tests {
                 vector_signed_long,
                 vector_unsigned_long
             );
-            #[cfg(all(target_arch = "aarch64", zerocopy_aarch64_simd))]
+            #[cfg(all(target_arch = "aarch64", zerocopy_aarch64_simd_1_59_0))]
             #[rustfmt::skip]
             test_simd_arch_mod!(
                 aarch64, float32x2_t, float32x4_t, float64x1_t, float64x2_t, int8x8_t, int8x8x2_t,

diff --git a/src/layout.rs b/src/layout.rs
@@ -880,7 +880,7 @@ mod tests {
                             layout(size_info, align).validate_cast_and_convert_metadata(addr, bytes_len, cast_type)
                         }).map_err(|d| {
                             let msg = d.downcast::<&'static str>().ok().map(|s| *s.as_ref());
-                            assert!(msg.is_some() || cfg!(not(zerocopy_panic_in_const_and_vec_try_reserve)), "non-string panic messages are not permitted when `--cfg zerocopy_panic_in_const_and_vec_try_reserve` is set");
+                            assert!(msg.is_some() || cfg!(not(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0)), "non-string panic messages are not permitted when `--cfg zerocopy_panic_in_const_and_vec_try_reserve` is set");
                             msg
                         });
                         std::panic::set_hook(previous_hook);