Documentation for PhantomDeserData

Author: vigna

README.md

@@ -108,7 +108,7 @@ These are the main limitations you should be aware of before choosing to use
   generated at deserialization time is stored in newly allocated memory. This is
   not the case with [Abomonation].
 
-## Example: Zero copy of standard types
+## Example: Zero-copy of standard types
 
 Let us start with the simplest case: data that can be zero-copy deserialized. In
 this case, we serialize an array of a thousand zeros, and get back a reference
@@ -664,6 +664,17 @@ the hood because `BitFieldVec` is ε-serde-aware, and in fact you will not even
 notice the difference if you access both versions using the trait
 `BitFieldSlice`.
 
+## [`PhantomData`]
+
+[`PhantomData`] undergoes a special treatment: its type parameter `T` does not
+have to be (de)serializable or sized—it is sufficient that it implements
+[`TypeHash`]. Moreover, `T` is not replaced with its associated
+(de)serialization type.
+
+There might be corner cases in which `T` appears both as a parameter of
+[`PhantomData`] and as a type parameter of a field of a type. In this case, you
+can use [`PhantomDeserData`] instead of [`PhantomData`].
+
 ## MemDbg / MemSize
 
 All ε-serde structures implement the [`MemDbg`] and [`MemSize`] traits.
@@ -723,3 +734,4 @@ European Union nor the Italian MUR can be held responsible for them.
 [`PhantomData`]: <https://doc.rust-lang.org/std/marker/struct.PhantomData.html>
 [`Iterator`]: <https://doc.rust-lang.org/std/iter/trait.Iterator.html>
 [`SerIter`]: <https://docs.rs/epserde/latest/epserde/impls/iter/struct.SerIter.html>
+[`PhantomDeserData`]: <https://docs.rs/epserde/latest/epserde/struct.PhantomDeserData.html>

epserde-derive/src/lib.rs

@@ -793,6 +793,10 @@ pub fn epserde_derive(input: TokenStream) -> TokenStream {
             let tag = (0..variants.len()).collect::<Vec<_>>();
 
             if is_zero_copy {
+                // In zero-copy types we do not need to add bounds to
+                // the associated SerType/DeserType, as generics are not
+                // replaced with their SerType/DeserType.
+
                 quote! {
                     #[automatically_derived]
                     impl<#impl_generics> epserde::traits::CopyType for  #name<#concat_generics> #where_clause {

epserde/src/lib.rs

@@ -45,6 +45,7 @@ pub mod prelude {
     pub use crate::ser::SerializeInner;
     pub use crate::traits::*;
     pub use crate::utils::*;
+    pub use crate::PhantomDeserData;
     #[cfg(feature = "derive")]
     pub use epserde_derive::Epserde;
 }
@@ -63,6 +64,37 @@ pub fn pad_align_to(value: usize, align_to: usize) -> usize {
     value.wrapping_neg() & (align_to - 1)
 }
 
+/// A type semantically equivalent to [`PhantomData`], but whose type parameter
+/// is replaced with its associated deserialization type.
+///
+/// In some case, you might find yourself with a deep-copy type that has a type
+/// parameter `T` appearing both in a field and in a [`PhantomData`]. In this
+/// case, the type will not compile, as in its associated deserialization type
+/// `T` will be replaced by `T::DeserType`, but the [`PhantomData`] field will
+/// still contain `T`. To fix this issue, you can use [`PhantomDeserData`]
+/// instead.
+///
+/// # Examples
+///
+/// This code will not compile:
+/// ```compile_fail
+/// use epserde::prelude::*;
+/// #[derive(Epserde, Debug, PartialEq, Eq, Clone, Default)]
+/// struct Data<T> {
+///     data: T,
+///     phantom: PhantomData<T>,
+/// }
+/// ```
+///
+/// This code, instead, will compile:
+/// ```
+/// use epserde::prelude::*;
+/// #[derive(Epserde, Debug, PartialEq, Eq, Clone, Default)]
+/// struct Data<T> {
+///     data: T,
+///     phantom: PhantomDeserData<T>,
+/// }
+/// ```
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct PhantomDeserData<T: ?Sized>(pub PhantomData<T>);