much more docs.

src/allocation.rs

@@ -1,7 +1,7 @@
 //! Stuff to boost things in the `alloc` crate.
 //!
-//! You must use the crate with the `extern_crate_alloc` feature for the content
+//! * You must enable the `extern_crate_alloc` feature of `bytemuck` or you will
-//! in this module to be compiled in!
+//!   not be able to use this module!
 
 use super::*;
 use alloc::{

src/lib.rs

@@ -1,4 +1,41 @@
 #![no_std]
+#![warn(missing_docs)]
+
+//! This crate gives small utilities for casting between plain data types.
+//!
+//! ## Basics
+//!
+//! Data comes in five basic forms in Rust, so we have five basic casting
+//! functions:
+//!
+//! * `T` uses [`cast`]
+//! * `&T` uses [`cast_ref`]
+//! * `&mut T` uses [`cast_mut`]
+//! * `&[T]` uses [`cast_slice`]
+//! * `&mut [T]` uses [`cast_slice_mut`]
+//!
+//! Some casts will never fail (eg: `cast::<u32, f32>` always works), other
+//! casts might fail (eg: `cast_ref::<[u8; 4], u32>` will fail if the reference
+//! isn't already aligned to 4). Each casting function has a "try" version which
+//! will return a `Result`, and the "normal" version which will simply panic on
+//! invalid input.
+//!
+//! ## Using Your Own Types
+//!
+//! All the functions here are guarded by the [`Pod`] trait, which is a
+//! sub-trait of the [`Zeroable`] trait.
+//!
+//! If you're very sure that your type is eligible, you can implement those
+//! traits for your type and then they'll have full casting support. However,
+//! these traits are `unsafe`, and you should carefully read the requirements
+//! before adding the them to your own types.
+//!
+//! ## Features
+//!
+//! * This crate is core only by default, but if you're using Rust 1.36 or later
+//!   you can enable the `extern_crate_alloc` cargo feature for some additional
+//!   methods related to `Box` and `Vec`. Note that the `docs.rs` documentation
+//!   is always built with `extern_crate_alloc` cargo feature enabled.
 
 #[cfg(target_arch = "x86")]
 pub(crate) use core::arch::x86;

src/pod.rs

@@ -16,10 +16,14 @@ use super::*;
 ///
 /// * The type must be inhabited (eg: no
 ///   [Infallible](core::convert::Infallible)).
-/// * The type must allow any bit pattern (eg: no `bool` or `char`).
+/// * The type must allow any bit pattern (eg: no `bool` or `char`, which have
-/// * The type must not contain any padding bytes (eg: no `(u8, u16)`).
+///   illegal bit patterns).
-/// * A struct needs to have all fields be `Pod` and be `repr(C)`,
+/// * The type must not contain any padding bytes, either in the middle or on
-///   `repr(transparent)`, or `repr(packed)`.
+///   the end (eg: no `#[repr(C)] struct Foo(u8, u16)`, which has padding in the
+///   middle, and also no `#[repr(C)] struct Foo(u16, u8)`, which has padding on
+///   the end).
+/// * The type needs to have all fields also be `Pod`.
+/// * The type needs to be `repr(C)`, `repr(transparent)`, or `repr(packed)`.
 pub unsafe trait Pod: Zeroable + Copy + 'static {}
 
 unsafe impl Pod for () {}

src/zeroable.rs

@@ -1,10 +1,14 @@
 use super::*;
 
-/// Trait for types that can be safely created with [`zeroed`](core::mem::zeroed).
+/// Trait for types that can be safely created with
+/// [`zeroed`](core::mem::zeroed).
+///
+/// An all-zeroes value may or may not be the same value as the
+/// [Default](core::default::Default) value of the type.
 ///
 /// ## Safety
 ///
-/// * Your type must be _inhabited_ (eg: no
+/// * Your type must be inhabited (eg: no
 ///   [Infallible](core::convert::Infallible)).
 /// * Your type must be allowed to be an "all zeroes" bit pattern (eg: no
 ///   [`NonNull<T>`](core::ptr::NonNull)).