From ac90bb517b587e37853185ed3719e17f1d487861 Mon Sep 17 00:00:00 2001 From: Joshua Liebow-Feeser Date: Tue, 14 Nov 2023 06:29:03 -0800 Subject: [PATCH] [doc] Use doc(cfg(...)) in more places (#599) Use the `doc(cfg(...))` syntax in more places when generating documentation: - `impl FromZeroes for Option>` - trait impls for simd types Release 0.7.26. Closes #597 --- Cargo.toml | 8 ++-- src/lib.rs | 97 +++++++++++++++++++++----------------- src/macros.rs | 9 +++- zerocopy-derive/Cargo.toml | 2 +- 4 files changed, 66 insertions(+), 50 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 09c1ff824e..9f38364d70 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,7 +15,7 @@ [package] edition = "2018" name = "zerocopy" -version = "0.7.25" +version = "0.7.26" authors = ["Joshua Liebow-Feeser "] description = "Utilities for zero-copy parsing and serialization" license = "BSD-2-Clause OR Apache-2.0 OR MIT" @@ -49,7 +49,7 @@ simd-nightly = ["simd"] __internal_use_only_features_that_work_on_stable = ["alloc", "derive", "simd"] [dependencies] -zerocopy-derive = { version = "=0.7.25", path = "zerocopy-derive", optional = true } +zerocopy-derive = { version = "=0.7.26", path = "zerocopy-derive", optional = true } [dependencies.byteorder] version = "1.3" @@ -60,7 +60,7 @@ optional = true # zerocopy-derive remain equal, even if the 'derive' feature isn't used. # See: https://github.com/matklad/macro-dep-test [target.'cfg(any())'.dependencies] -zerocopy-derive = { version = "=0.7.25", path = "zerocopy-derive" } +zerocopy-derive = { version = "=0.7.26", path = "zerocopy-derive" } [dev-dependencies] assert_matches = "1.5" @@ -75,6 +75,6 @@ testutil = { path = "testutil" } # CI test failures. trybuild = { version = "=1.0.85", features = ["diff"] } # In tests, unlike in production, zerocopy-derive is not optional -zerocopy-derive = { version = "=0.7.25", path = "zerocopy-derive" } +zerocopy-derive = { version = "=0.7.26", path = "zerocopy-derive" } # TODO(#381) Remove this dependency once we have our own layout gadgets. elain = "0.3.0" diff --git a/src/lib.rs b/src/lib.rs index 6b8dfe92b9..04f46f1542 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1926,7 +1926,10 @@ safety_comment! { /// TODO(#429), TODO(https://github.com/rust-lang/rust/pull/115333): Cite /// the Stable docs once they're available. #[cfg(feature = "alloc")] - unsafe_impl!(T => FromZeroes for Option>); + unsafe_impl!( + #[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] + T => FromZeroes for Option> + ); unsafe_impl!(T => FromZeroes for Option<&'_ T>); unsafe_impl!(T => FromZeroes for Option<&'_ mut T>); unsafe_impl!(T => FromZeroes for Option>); @@ -2149,6 +2152,7 @@ safety_comment! { // [1] https://rust-lang.github.io/unsafe-code-guidelines/layout/packed-simd-vectors.html // [2] https://github.com/rust-lang/unsafe-code-guidelines/issues/38 #[cfg(feature = "simd")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "simd")))] mod simd { /// Defines a module which implements `FromZeroes`, `FromBytes`, and /// `AsBytes` for a set of types from a module in `core::arch`. @@ -2160,7 +2164,9 @@ mod simd { // target/feature combinations don't emit any impls // and thus don't use this macro. macro_rules! simd_arch_mod { - ($arch:ident, $mod:ident, $($typ:ident),*) => { + (#[cfg $cfg:tt] $arch:ident, $mod:ident, $($typ:ident),*) => { + #[cfg $cfg] + #[cfg_attr(doc_cfg, doc(cfg $cfg))] mod $mod { use core::arch::$arch::{$($typ),*}; @@ -2175,48 +2181,51 @@ mod simd { }; } - #[cfg(target_arch = "x86")] - simd_arch_mod!(x86, x86, __m128, __m128d, __m128i, __m256, __m256d, __m256i); - #[cfg(all(feature = "simd-nightly", target_arch = "x86"))] - simd_arch_mod!(x86, x86_nightly, __m512bh, __m512, __m512d, __m512i); - #[cfg(target_arch = "x86_64")] - simd_arch_mod!(x86_64, x86_64, __m128, __m128d, __m128i, __m256, __m256d, __m256i); - #[cfg(all(feature = "simd-nightly", target_arch = "x86_64"))] - simd_arch_mod!(x86_64, x86_64_nightly, __m512bh, __m512, __m512d, __m512i); - #[cfg(target_arch = "wasm32")] - simd_arch_mod!(wasm32, wasm32, v128); - #[cfg(all(feature = "simd-nightly", target_arch = "powerpc"))] - simd_arch_mod!( - powerpc, - powerpc, - vector_bool_long, - vector_double, - vector_signed_long, - vector_unsigned_long - ); - #[cfg(all(feature = "simd-nightly", target_arch = "powerpc64"))] - simd_arch_mod!( - powerpc64, - powerpc64, - vector_bool_long, - vector_double, - vector_signed_long, - vector_unsigned_long - ); - #[cfg(target_arch = "aarch64")] #[rustfmt::skip] - simd_arch_mod!( - aarch64, aarch64, float32x2_t, float32x4_t, float64x1_t, float64x2_t, int8x8_t, int8x8x2_t, - int8x8x3_t, int8x8x4_t, int8x16_t, int8x16x2_t, int8x16x3_t, int8x16x4_t, int16x4_t, - int16x8_t, int32x2_t, int32x4_t, int64x1_t, int64x2_t, poly8x8_t, poly8x8x2_t, poly8x8x3_t, - poly8x8x4_t, poly8x16_t, poly8x16x2_t, poly8x16x3_t, poly8x16x4_t, poly16x4_t, poly16x8_t, - poly64x1_t, poly64x2_t, uint8x8_t, uint8x8x2_t, uint8x8x3_t, uint8x8x4_t, uint8x16_t, - uint8x16x2_t, uint8x16x3_t, uint8x16x4_t, uint16x4_t, uint16x8_t, uint32x2_t, uint32x4_t, - uint64x1_t, uint64x2_t - ); - #[cfg(all(feature = "simd-nightly", target_arch = "arm"))] - #[rustfmt::skip] - simd_arch_mod!(arm, arm, int8x4_t, uint8x4_t); + const _: () = { + simd_arch_mod!( + #[cfg(target_arch = "x86")] + x86, x86, __m128, __m128d, __m128i, __m256, __m256d, __m256i + ); + simd_arch_mod!( + #[cfg(all(feature = "simd-nightly", target_arch = "x86"))] + x86, x86_nightly, __m512bh, __m512, __m512d, __m512i + ); + simd_arch_mod!( + #[cfg(target_arch = "x86_64")] + x86_64, x86_64, __m128, __m128d, __m128i, __m256, __m256d, __m256i + ); + simd_arch_mod!( + #[cfg(all(feature = "simd-nightly", target_arch = "x86_64"))] + x86_64, x86_64_nightly, __m512bh, __m512, __m512d, __m512i + ); + simd_arch_mod!( + #[cfg(target_arch = "wasm32")] + wasm32, wasm32, v128 + ); + simd_arch_mod!( + #[cfg(all(feature = "simd-nightly", target_arch = "powerpc"))] + powerpc, powerpc, vector_bool_long, vector_double, vector_signed_long, vector_unsigned_long + ); + simd_arch_mod!( + #[cfg(all(feature = "simd-nightly", target_arch = "powerpc64"))] + powerpc64, powerpc64, vector_bool_long, vector_double, vector_signed_long, vector_unsigned_long + ); + simd_arch_mod!( + #[cfg(target_arch = "aarch64")] + aarch64, aarch64, float32x2_t, float32x4_t, float64x1_t, float64x2_t, int8x8_t, int8x8x2_t, + int8x8x3_t, int8x8x4_t, int8x16_t, int8x16x2_t, int8x16x3_t, int8x16x4_t, int16x4_t, + int16x8_t, int32x2_t, int32x4_t, int64x1_t, int64x2_t, poly8x8_t, poly8x8x2_t, poly8x8x3_t, + poly8x8x4_t, poly8x16_t, poly8x16x2_t, poly8x16x3_t, poly8x16x4_t, poly16x4_t, poly16x8_t, + poly64x1_t, poly64x2_t, uint8x8_t, uint8x8x2_t, uint8x8x3_t, uint8x8x4_t, uint8x16_t, + uint8x16x2_t, uint8x16x3_t, uint8x16x4_t, uint16x4_t, uint16x8_t, uint32x2_t, uint32x4_t, + uint64x1_t, uint64x2_t + ); + simd_arch_mod!( + #[cfg(all(feature = "simd-nightly", target_arch = "arm"))] + arm, arm, int8x4_t, uint8x4_t + ); + }; } /// Safely transmutes a value of one type to a value of another type of the same @@ -3658,6 +3667,7 @@ unsafe impl<'a> ByteSliceMut for &'a mut [u8] {} unsafe impl<'a> ByteSliceMut for RefMut<'a, [u8]> {} #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] mod alloc_support { use alloc::vec::Vec; @@ -3875,7 +3885,6 @@ mod alloc_support { } #[cfg(feature = "alloc")] -#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] #[doc(inline)] pub use alloc_support::*; diff --git a/src/macros.rs b/src/macros.rs index 5aadc61798..ea4f3603c6 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -35,7 +35,8 @@ macro_rules! safety_comment { /// Unsafely implements trait(s) for a type. macro_rules! unsafe_impl { // Implement `$trait` for `$ty` with no bounds. - ($ty:ty: $trait:ty) => { + ($(#[$attr:meta])* $ty:ty: $trait:ty) => { + $(#[$attr])* unsafe impl $trait for $ty { #[allow(clippy::missing_inline_in_public_items)] fn only_derive_is_allowed_to_implement_this_trait() {} } }; // Implement all `$traits` for `$ty` with no bounds. @@ -68,33 +69,39 @@ macro_rules! unsafe_impl { // The following arm has the same behavior with the exception of the lack of // support for a leading `const` parameter. ( + $(#[$attr:meta])* const $constname:ident : $constty:ident $(,)? $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),* => $trait:ident for $ty:ty ) => { unsafe_impl!( @inner + $(#[$attr])* @const $constname: $constty, $($tyvar $(: $(? $optbound +)* + $($bound +)*)?,)* => $trait for $ty ); }; ( + $(#[$attr:meta])* $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),* => $trait:ident for $ty:ty ) => { unsafe_impl!( @inner + $(#[$attr])* $($tyvar $(: $(? $optbound +)* + $($bound +)*)?,)* => $trait for $ty ); }; ( @inner + $(#[$attr:meta])* $(@const $constname:ident : $constty:ident,)* $($tyvar:ident $(: $(? $optbound:ident +)* + $($bound:ident +)* )?,)* => $trait:ident for $ty:ty ) => { + $(#[$attr])* unsafe impl<$(const $constname: $constty,)* $($tyvar $(: $(? $optbound +)* $($bound +)*)?),*> $trait for $ty { #[allow(clippy::missing_inline_in_public_items)] fn only_derive_is_allowed_to_implement_this_trait() {} diff --git a/zerocopy-derive/Cargo.toml b/zerocopy-derive/Cargo.toml index c73599586d..5d7649a9a9 100644 --- a/zerocopy-derive/Cargo.toml +++ b/zerocopy-derive/Cargo.toml @@ -9,7 +9,7 @@ [package] edition = "2018" name = "zerocopy-derive" -version = "0.7.25" +version = "0.7.26" authors = ["Joshua Liebow-Feeser "] description = "Custom derive for traits from the zerocopy crate" license = "BSD-2-Clause OR Apache-2.0 OR MIT"