Document ZeroCopy derive

crates/musli-macros/src/zero_copy.rs

@@ -147,7 +147,7 @@ fn expand(cx: &Ctxt, input: &DeriveInput) -> Result<TokenStream, ()> {
     let error: syn::Path = syn::parse_quote!(#krate::Error);
     let validator: syn::Path = syn::parse_quote!(#krate::Validator);
     let zero_copy: syn::Path = syn::parse_quote!(#krate::ZeroCopy);
-    let result: syn::Path = syn::parse_quote!(core::result::Result);
+    let result: syn::Path = syn::parse_quote!(#krate::__private::result::Result);
 
     let mut const_asserts = Vec::new();
     let mut padding = Vec::new();

crates/musli-zerocopy/src/lib.rs

@@ -88,6 +88,73 @@ pub use self::r#unsized::Unsized;
 mod r#unsized;
 
 pub use self::zero_copy::{UnsizedZeroCopy, ZeroCopy};
+
+/// Derive macro to implement [`ZeroCopy`].
+///
+/// # Examples
+///
+/// ```
+/// use musli_zerocopy::{AlignedBuf, ZeroCopy};
+///
+/// #[derive(ZeroCopy)]
+/// #[repr(C, align(128))]
+/// struct Custom {
+///     field: u32,
+/// }
+///
+/// let mut buf = AlignedBuf::new();
+/// buf.write(&Custom { field: 10 });
+/// ```
+///
+/// # Attributes
+///
+/// ## Type attributes
+///
+/// The following `repr` attributes are supported:
+/// * repr(C) - Ensures that the type has the mandatory represention.
+/// * repr(transparent) - If there is a single field inside of the marked struct
+///   which implements `ZeroCopy`.
+/// * repr(align(..)) - Allows for control over the struct alignment.
+///
+/// The following `zero_copy(..)` attribute are supported:
+///
+/// ### `zero_copy(bounds = {<bound>,*})`
+///
+/// Allows for adding additional bounds to implement `ZeroCopy` for generic
+/// types:
+///
+/// ```
+/// use musli_zerocopy::ZeroCopy;
+///
+/// #[derive(ZeroCopy)]
+/// #[repr(C)]
+/// #[zero_copy(bounds = {A: ZeroCopy, B: ZeroCopy})]
+/// struct Pair<A, B> {
+///     left: A,
+///     right: B,
+/// }
+/// ```
+///
+/// ### `zero_copy(crate = <path>)`
+///
+/// Allows for specifying a custom path to the `musli_zerocopy`` crate
+/// (default).
+///
+/// ```
+/// use musli_zerocopy as zerocopy;
+///
+/// use zerocopy::ZeroCopy;
+///
+/// #[derive(ZeroCopy)]
+/// #[repr(C)]
+/// #[zero_copy(crate = zerocopy)]
+/// struct Custom {
+///     field: u32,
+/// }
+/// ```
+#[doc(inline)]
+pub use musli_macros::ZeroCopy;
+
 mod zero_copy;
 
 mod map;
@@ -105,3 +172,8 @@ mod tests;
 // Sentinel used to allow for `#[zero_copy(ignore)]` to work in this crate.
 #[allow(unused)]
 const ZERO_COPY_IGNORE_IS_NOT_SAFE_TO_USE: () = ();
+
+#[doc(hidden)]
+pub mod __private {
+    pub use ::core::result;
+}

crates/musli-zerocopy/src/pair.rs

@@ -1,4 +1,4 @@
-use crate::zero_copy::ZeroCopy;
+use crate::ZeroCopy;
 
 /// A pair of values which can be stored inside of any other zero copy
 /// structure.

crates/musli-zerocopy/src/ptr.rs

@@ -1,6 +1,6 @@
 use core::fmt;
 
-use crate::zero_copy::ZeroCopy;
+use crate::ZeroCopy;
 
 /// An absolute pointer to a location in a [`Buf`].
 ///

crates/musli-zerocopy/src/ref.rs

@@ -1,7 +1,7 @@
 use core::marker::PhantomData;
 
 use crate::ptr::Ptr;
-use crate::zero_copy::ZeroCopy;
+use crate::ZeroCopy;
 
 /// A sized reference.
 ///

crates/musli-zerocopy/src/slice.rs

@@ -1,7 +1,7 @@
 use core::marker::PhantomData;
 
 use crate::ptr::Ptr;
-use crate::zero_copy::ZeroCopy;
+use crate::ZeroCopy;
 
 /// A reference to a slice packed as a wide pointer.
 ///

crates/musli-zerocopy/src/unsized.rs

@@ -1,7 +1,7 @@
 use core::marker::PhantomData;
 
 use crate::ptr::Ptr;
-use crate::zero_copy::ZeroCopy;
+use crate::ZeroCopy;
 
 /// A reference to an unsized value packed as a wide pointer.
 ///

crates/musli-zerocopy/src/zero_copy.rs

@@ -7,9 +7,6 @@ use core::str;
 use crate::buf::{AnyValue, Buf, BufMut};
 use crate::error::{Error, ErrorKind};
 
-#[doc(inline)]
-pub use musli_macros::ZeroCopy;
-
 /// Trait governing which `T` in [`Unsized<T>`] the wrapper can handle.
 ///
 /// We only support slice-like, unaligned unsized types, such as `str` and