Document that NotNan is repr(transparent).

Currently, rustdoc only displays `repr(transparent)` if the type’s
fields are public, so there is no indication in the documentation that
`NotNan` has `repr(transparent)`. Even if it was visible, there is not
currently a strong consensus that such a repr may be assumed to be a
stable part of the public API.

Therefore, add paragraphs to `NotNan` and `OrderedFloat`’s documentation
guaranteeing the repr. I also mentioned `bytemuck` so as to not be
encouraging unsafe code, though the phrasing isn’t great.

Author: kpreid

src/lib.rs

@@ -75,6 +75,18 @@ fn canonicalize_signed_zero<T: FloatCore>(x: T) -> T {
 /// s.insert(OrderedFloat(NAN));
 /// assert!(s.contains(&OrderedFloat(NAN)));
 /// ```
+///
+/// # Representation
+///
+/// `OrderedFloat` has `#[repr(transparent)]` and permits any value, so it is sound to use
+/// [transmute](core::mem::transmute) or pointer casts to convert between any type `T` and
+/// `OrderedFloat<T>`.
+/// However, consider using [`bytemuck`] as a safe alternative if possible.
+///
+#[cfg_attr(
+    not(feature = "bytemuck"),
+    doc = "[`bytemuck`]: https://docs.rs/bytemuck/1/"
+)]
 #[derive(Default, Clone, Copy)]
 #[repr(transparent)]
 pub struct OrderedFloat<T>(pub T);
@@ -1157,6 +1169,18 @@ impl<T: FloatCore + Num> Num for OrderedFloat<T> {
 /// // This will panic:
 /// let c = a + b;
 /// ```
+///
+/// # Representation
+///
+/// `NotNan` has `#[repr(transparent)]`, so it is sound to use
+/// [transmute](core::mem::transmute) or pointer casts to convert between any type `T` and
+/// `NotNan<T>`, as long as this does not create a NaN value.
+/// However, consider using [`bytemuck`] as a safe alternative if possible.
+///
+#[cfg_attr(
+    not(feature = "bytemuck"),
+    doc = "[`bytemuck`]: https://docs.rs/bytemuck/1/"
+)]
 #[derive(PartialOrd, PartialEq, Default, Clone, Copy)]
 #[repr(transparent)]
 pub struct NotNan<T>(T);