From aa36f39d6a38ab9b406f0d96aab235304937eb1e Mon Sep 17 00:00:00 2001
From: "Alexandre A. Bizri" <alexandre@bizri.fr>
Date: Wed, 25 Sep 2019 15:57:25 -0400
Subject: [PATCH] Document safety requirements for implementing OclPrm

---
 ocl-core/src/lib.rs | 43 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/ocl-core/src/lib.rs b/ocl-core/src/lib.rs
index 57a6f53a0..fbe8f38c1 100644
--- a/ocl-core/src/lib.rs
+++ b/ocl-core/src/lib.rs
@@ -237,7 +237,48 @@ mod traits {
     /// and their vector counterparts (ex.: cl_int4, cl_float3, cl_short16);
     ///
     /// Can also be implemented for custom types as long as layout and
-    /// alignment are conserved between Rust and OpenCL (repr "C").
+    /// alignment are conserved between Rust and OpenCL (repr "C"), and where
+    /// every possible bit configuration can be interpreted as a valid Rust type.
+    ///
+    /// See the [Nomicon] for more information on valid and invalid bit configurations for types.
+    ///
+    /// ## Examples of valid and invalid implementing types
+    ///
+    /// ### Valid
+    /// ```rust,ignore
+    /// #[repr(C)]
+    /// struct Valid{
+    ///     a: f32,
+    ///     b: u8,
+    /// }
+    /// ```
+    ///
+    /// Here, the layout is valid (`#[repr(C)]`), and any byte configuration are valid,
+    /// as any appropriately-sized byte slice can be interpreted as  u8, u16, u32, u64, f32 and f64.
+    ///
+    /// ### Invalid
+    /// ```rust,ignore
+    /// #[repr(C)]
+    /// struct Invalid{
+    ///     a: char,
+    ///     b: u16,
+    /// }
+    /// ```
+    ///
+    /// Here, while the layout is still valid, the presence of a `char` member makes it invalid,
+    /// as a char is only valid inside the ranges \[0x0, 0xD7FF\] and \[0xE000, 0x10FFFF\].
+    ///
+    /// ```rust,ignore
+    /// #[repr(C)]
+    /// struct Invalid{
+    ///     a: f32,
+    ///     b: bool,
+    /// }
+    /// ```
+    ///
+    /// Here the `bool` makes it invalid, as a bool is only valid on values 0 and 1.
+    ///
+    /// [Nomicon]: https://doc.rust-lang.org/nomicon/what-unsafe-does.html?highlight=primitive#what-unsafe-rust-can-do
     pub unsafe trait OclPrm: Debug + Clone + Copy + Default + PartialEq + Send + Sync + 'static {}
 
     impl_unsafe!(OclPrm: u8, i8, u16, i16, u32, i32, u64, i64, usize, isize, f32, f64,