more general approach of hedging against library updates

rust-lang · Sep 2, 2023 · b1a7983 · b1a7983
1 parent ee09160
commit b1a7983
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 4 deletions.
diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs
@@ -1545,8 +1545,8 @@ mod prim_ref {}
 ///   `NonNull<T>` are all ABI-compatible with each other.
 /// - Any two `fn()` types with the same `extern` ABI string are ABI-compatible with each other.
 /// - Any two 1-ZST types (types with size 0 and alignment 1) are ABI-compatible.
-/// - A `repr(transparent)` type `T` that has no private fields and is not `#[non_exhaustive]` is
-///   ABI-compatible with its unique non-1-ZST field (if there is such a field).
+/// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-1-ZST field (if there is
+///   such a field).
 /// - `i32` is ABI-compatible with `NonZeroI32`, and similar for all other integer types with their
 ///   matching `NonZero*` type.
 /// - If `T` is guaranteed to be subject to the [null pointer
@@ -1560,6 +1560,13 @@ mod prim_ref {}
 /// the remaining bits in the register that are not used by the value. `i32` vs `f32` has already
 /// been mentioned above.
 ///
+/// Note that these rules describe when two completely known types are ABI-compatible. When
+/// considering ABI compatibility of a type declared in another crate (including the standard
+/// library), consider that any type that has a private field or the `#[non_exhaustive]` attribute
+/// may change its layout as a non-breaking update unless documented otherwise -- so for instance,
+/// even if such a type is a 1-ZST or `repr(transparent)` right now, this might change with any
+/// library version change.
+///
 /// ### Trait implementations
 ///
 /// In this documentation the shorthand `fn (T₁, T₂, …, Tₙ)` is used to represent non-variadic

diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs
@@ -1545,8 +1545,8 @@ mod prim_ref {}
 ///   `NonNull<T>` are all ABI-compatible with each other.
 /// - Any two `fn()` types with the same `extern` ABI string are ABI-compatible with each other.
 /// - Any two 1-ZST types (types with size 0 and alignment 1) are ABI-compatible.
-/// - A `repr(transparent)` type `T` that has no private fields and is not `#[non_exhaustive]` is
-///   ABI-compatible with its unique non-1-ZST field (if there is such a field).
+/// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-1-ZST field (if there is
+///   such a field).
 /// - `i32` is ABI-compatible with `NonZeroI32`, and similar for all other integer types with their
 ///   matching `NonZero*` type.
 /// - If `T` is guaranteed to be subject to the [null pointer
@@ -1560,6 +1560,13 @@ mod prim_ref {}
 /// the remaining bits in the register that are not used by the value. `i32` vs `f32` has already
 /// been mentioned above.
 ///
+/// Note that these rules describe when two completely known types are ABI-compatible. When
+/// considering ABI compatibility of a type declared in another crate (including the standard
+/// library), consider that any type that has a private field or the `#[non_exhaustive]` attribute
+/// may change its layout as a non-breaking update unless documented otherwise -- so for instance,
+/// even if such a type is a 1-ZST or `repr(transparent)` right now, this might change with any
+/// library version change.
+///
 /// ### Trait implementations
 ///
 /// In this documentation the shorthand `fn (T₁, T₂, …, Tₙ)` is used to represent non-variadic