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.
This commit is contained in:
José Luis Cruz 2023-09-05 21:39:41 +02:00 committed by GitHub
parent 58445b1250
commit f047fb6aeb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 29 additions and 0 deletions

4
.cargo/config.toml Normal file
View File

@ -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"

View File

@ -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",

View File

@ -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
{}

View File

@ -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 {

View File

@ -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]`.

View File

@ -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,

View File

@ -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,

View File

@ -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> {}