improve documentation for optional features (#203)

- new feature `nightly_docs` enables `doc_cfg` unstable feature that allows showing explicit dependencies on features.
- new cargo alias `nightly_docs` for a more convenient local documentation build `cargo +nightly nightly_docs --open`.
- annotate exported items and implementations depending on some feature with the corresponding `doc(cfg())` attribute.
- add the `nightly_docs` feature to the `[package.metadata.docs.rs]` section.

.cargo/config.toml

@@ -0,0 +1,4 @@
+[alias]
+
+# The list of features should be the same as the one under `[package.metadata.docs.rs]`
+nightly_docs = "doc --no-deps -F nightly_docs,derive,extern_crate_alloc,extern_crate_std,zeroable_maybe_uninit,zeroable_atomics,min_const_generics,wasm_simd,must_cast"

Cargo.toml

@@ -30,12 +30,16 @@ unsound_ptr_pod_impl = []
 nightly_portable_simd = []
 nightly_stdsimd = []
 
+# Improved documentation using the nightly toolchain
+nightly_docs = []
+
 [dependencies]
 bytemuck_derive = { version = "1.4", path = "derive", optional = true }
 
 [package.metadata.docs.rs]
 # Note(Lokathor): Don't use all-features or it would use `unsound_ptr_pod_impl` too.
 features = [
+  "nightly_docs",
   "derive",
   "extern_crate_alloc",
   "extern_crate_std",

src/anybitpattern.rs

@@ -56,5 +56,6 @@ pub unsafe trait AnyBitPattern:
 unsafe impl<T: Pod> AnyBitPattern for T {}
 
 #[cfg(feature = "zeroable_maybe_uninit")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "zeroable_maybe_uninit")))]
 unsafe impl<T> AnyBitPattern for core::mem::MaybeUninit<T> where T: AnyBitPattern
 {}

src/checked.rs

@@ -224,6 +224,7 @@ impl core::fmt::Display for CheckedCastError {
   }
 }
 #[cfg(feature = "extern_crate_std")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "extern_crate_std")))]
 impl std::error::Error for CheckedCastError {}
 
 impl From<crate::PodCastError> for CheckedCastError {

src/lib.rs

@@ -2,6 +2,7 @@
 #![warn(missing_docs)]
 #![allow(clippy::match_like_matches_macro)]
 #![allow(clippy::uninlined_format_args)]
+#![cfg_attr(feature = "nightly_docs", feature(doc_cfg))]
 #![cfg_attr(feature = "nightly_portable_simd", feature(portable_simd))]
 #![cfg_attr(feature = "nightly_stdsimd", feature(stdsimd))]
 
@@ -91,6 +92,7 @@ extern crate std;
 #[cfg(feature = "extern_crate_alloc")]
 extern crate alloc;
 #[cfg(feature = "extern_crate_alloc")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "extern_crate_alloc")))]
 pub mod allocation;
 #[cfg(feature = "extern_crate_alloc")]
 pub use allocation::*;
@@ -116,6 +118,7 @@ pub use pod_in_option::*;
 #[cfg(feature = "must_cast")]
 mod must;
 #[cfg(feature = "must_cast")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "must_cast")))]
 pub use must::*;
 
 mod no_uninit;
@@ -131,6 +134,7 @@ mod transparent;
 pub use transparent::*;
 
 #[cfg(feature = "derive")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "derive")))]
 pub use bytemuck_derive::{
   AnyBitPattern, ByteEq, ByteHash, CheckedBitPattern, Contiguous, NoUninit,
   Pod, TransparentWrapper, Zeroable,
@@ -165,6 +169,7 @@ impl core::fmt::Display for PodCastError {
   }
 }
 #[cfg(feature = "extern_crate_std")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "extern_crate_std")))]
 impl std::error::Error for PodCastError {}
 
 /// Re-interprets `&T` as `&[u8]`.

src/pod.rs

@@ -54,10 +54,13 @@ unsafe impl Pod for f64 {}
 unsafe impl<T: Pod> Pod for Wrapping<T> {}
 
 #[cfg(feature = "unsound_ptr_pod_impl")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "unsound_ptr_pod_impl")))]
 unsafe impl<T: 'static> Pod for *mut T {}
 #[cfg(feature = "unsound_ptr_pod_impl")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "unsound_ptr_pod_impl")))]
 unsafe impl<T: 'static> Pod for *const T {}
 #[cfg(feature = "unsound_ptr_pod_impl")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "unsound_ptr_pod_impl")))]
 unsafe impl<T: 'static> PodInOption for NonNull<T> {}
 
 unsafe impl<T: ?Sized + 'static> Pod for PhantomData<T> {}
@@ -67,6 +70,7 @@ unsafe impl<T: Pod> Pod for ManuallyDrop<T> {}
 // Note(Lokathor): MaybeUninit can NEVER be Pod.
 
 #[cfg(feature = "min_const_generics")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "min_const_generics")))]
 unsafe impl<T, const N: usize> Pod for [T; N] where T: Pod {}
 
 #[cfg(not(feature = "min_const_generics"))]
@@ -124,6 +128,7 @@ impl_unsafe_marker_for_simd!(
 );
 
 #[cfg(feature = "nightly_portable_simd")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "nightly_portable_simd")))]
 unsafe impl<T, const N: usize> Pod for core::simd::Simd<T, N>
 where
   T: core::simd::SimdElement + Pod,
@@ -132,6 +137,7 @@ where
 }
 
 #[cfg(all(target_arch = "x86", feature = "nightly_stdsimd"))]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "nightly_stdsimd")))]
 impl_unsafe_marker_for_simd!(
     unsafe impl Pod for x86::{
         __m128bh, __m256bh, __m512,
@@ -140,6 +146,7 @@ impl_unsafe_marker_for_simd!(
 );
 
 #[cfg(all(target_arch = "x86_64", feature = "nightly_stdsimd"))]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "nightly_stdsimd")))]
 impl_unsafe_marker_for_simd!(
     unsafe impl Pod for x86_64::{
         __m128bh, __m256bh, __m512,

src/zeroable.rs

@@ -71,6 +71,7 @@ unsafe impl<T: Zeroable> Zeroable for core::cell::UnsafeCell<T> {}
 unsafe impl<T: Zeroable> Zeroable for core::cell::Cell<T> {}
 
 #[cfg(feature = "zeroable_atomics")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "zeroable_atomics")))]
 mod atomic_impls {
   use super::Zeroable;
 
@@ -106,6 +107,7 @@ mod atomic_impls {
 }
 
 #[cfg(feature = "zeroable_maybe_uninit")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "zeroable_maybe_uninit")))]
 unsafe impl<T> Zeroable for core::mem::MaybeUninit<T> {}
 
 unsafe impl<A: Zeroable> Zeroable for (A,) {}
@@ -154,6 +156,7 @@ unsafe impl<
 }
 
 #[cfg(feature = "min_const_generics")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "min_const_generics")))]
 unsafe impl<T, const N: usize> Zeroable for [T; N] where T: Zeroable {}
 
 #[cfg(not(feature = "min_const_generics"))]
@@ -211,6 +214,7 @@ impl_unsafe_marker_for_simd!(
 );
 
 #[cfg(feature = "nightly_portable_simd")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "nightly_portable_simd")))]
 unsafe impl<T, const N: usize> Zeroable for core::simd::Simd<T, N>
 where
   T: core::simd::SimdElement + Zeroable,
@@ -219,6 +223,7 @@ where
 }
 
 #[cfg(all(target_arch = "x86", feature = "nightly_stdsimd"))]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "nightly_std_simd")))]
 impl_unsafe_marker_for_simd!(
     unsafe impl Zeroable for x86::{
         __m128bh, __m256bh, __m512,
@@ -227,6 +232,7 @@ impl_unsafe_marker_for_simd!(
 );
 
 #[cfg(all(target_arch = "x86_64", feature = "nightly_stdsimd"))]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "nightly_std_simd")))]
 impl_unsafe_marker_for_simd!(
     unsafe impl Zeroable for x86_64::{
         __m128bh, __m256bh, __m512,

src/zeroable_in_option.rs

@@ -31,4 +31,5 @@ unsafe impl<T: ?Sized> ZeroableInOption for &'_ T {}
 unsafe impl<T: ?Sized> ZeroableInOption for &'_ mut T {}
 
 #[cfg(feature = "extern_crate_alloc")]
+#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "extern_crate_alloc")))]
 unsafe impl<T: ?Sized> ZeroableInOption for alloc::boxed::Box<T> {}