[doc] Document rustc type privacy bug

See #1292

Makes progress towards #671

Author: jswrenn

src/lib.rs

@@ -446,6 +446,40 @@ use {FromZeros as FromZeroes, IntoBytes as AsBytes, Ref as LayoutVerified};
 ///
 /// This derive cannot currently be applied to unsized structs without an
 /// explicit `repr` attribute.
+///
+/// Some invocations of this derive run afoul of a [known bug] in Rust's type
+/// privacy checker. For example, this code:
+///
+/// ```compile_fail,E0446
+/// use zerocopy::*;
+/// # use zerocopy_derive::*;
+///
+/// #[derive(KnownLayout)]
+/// #[repr(C)]
+/// pub struct PublicType(PrivateType);
+///
+/// #[derive(KnownLayout)]
+/// struct PrivateType;
+/// ```
+///
+/// ...results in a compilation error:
+///
+/// ```text
+/// error[E0446]: private type `PrivateType` in public interface
+///  --> examples/bug.rs:3:10
+///   |
+/// 3 | #[derive(KnownLayout)]
+///   |          ^^^^^^^^^^^ can't leak private type
+/// ...
+/// 8 | struct PrivateType;
+///   | ------------------- `PrivateType` declared as private
+///   |
+///   = note: this error originates in the derive macro `KnownLayout` (in Nightly builds, run with -Z macro-backtrace for more info)
+/// ```
+///
+/// To work around this bug, mark private field types as `pub` and annotate them with `#[doc(hidden)]`.
+///
+/// [known bug]: https://github.com/rust-lang/rust/issues/45713
 #[cfg(any(feature = "derive", test))]
 #[cfg_attr(doc_cfg, doc(cfg(feature = "derive")))]
 pub use zerocopy_derive::KnownLayout;