wording improvements

rust-lang · Sep 4, 2023 · f9bcda9 · f9bcda9
1 parent 037afca
commit f9bcda9
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 16 deletions.
diff --git a/library/core/src/option.rs b/library/core/src/option.rs
@@ -119,7 +119,7 @@
 //! # Representation
 //!
 //! Rust guarantees to optimize the following types `T` such that
-//! [`Option<T>`] has the same size and alignment as `T`:
+//! [`Option<T>`] has the same size, alignment, and [function call ABI] as `T`:
 //!
 //! * [`Box<U>`]
 //! * `&U`
@@ -129,11 +129,12 @@
 //! * [`ptr::NonNull<U>`]
 //! * `#[repr(transparent)]` struct around one of the types in this list.
 //!
-//! [^extern_fn]: this remains true for any other ABI: `extern "abi" fn` (_e.g._, `extern "system" fn`)
+//! [^extern_fn]: this remains true for any argument/return types and any other ABI: `extern "abi" fn` (_e.g._, `extern "system" fn`)
 //!
 //! [`Box<U>`]: ../../std/boxed/struct.Box.html
 //! [`num::NonZero*`]: crate::num
 //! [`ptr::NonNull<U>`]: crate::ptr::NonNull
+//! [function call ABI]: ../primitive.fn.html#abi-compatibility
 //!
 //! This is called the "null pointer optimization" or NPO.
 //!

diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs
@@ -1544,28 +1544,35 @@ mod prim_ref {}
 ///
 /// The following types are guaranteed to be ABI-compatible:
 ///
-/// - Every type is ABI-compatible with itself.
 /// - `*const T`, `*mut T`, `&T`, `&mut T`, `Box<T>`, `NonNull<T>` are all ABI-compatible with each
 ///   other for all `T`.
-/// - 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` is ABI-compatible with its unique non-1-ZST field (if there is
-///   such a field).
+/// - Any two `fn`/`extern "ABI" fn` types with the same call ABI are ABI-compatible with each
+///   other, independent of the rest of their signature.
+/// - Any two types with size 0 and alignment 1 are ABI-compatible.
+/// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-trivial field, i.e., the
+///   unique field that doesn't have size 0 and alignment 1 (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
 ///   optimization](option/index.html#representation), then `T` and `Option<T>` are ABI-compatible.
+///
+/// Furthermore, ABI compatibility satisfies the following general properties:
+///
+/// - Every type is ABI-compatible with itself.
 /// - If `T1` and `T2` are ABI-compatible, then two `repr(C)` types that only differ because one
 ///   field type was changed from `T1` to `T2` are ABI-compatible.
-/// - ABI-compatibility is symmetric and transitive.
+/// - If `T1` and `T2` are ABI-compatible and `T2` and `T3` are ABI-compatible, then so are `T1` and
+///   `T3` (i.e., ABI-compatibility is transitive).
+/// - If `T1` and `T2` are ABI-compatible, then so are `T2` and `T1` (i.e., ABI-compatibility is
+///   symmetric).
 ///
 /// More signatures can be ABI-compatible on specific targets, but that should not be relied upon
 /// since it is not portable and not a stable guarantee.
 ///
 /// Noteworthy cases of types *not* being ABI-compatible in general are `bool` vs `u8`, and `i32` vs
 /// `u32`: on some targets, the calling conventions for these types differ in terms of what they
 /// guarantee for the remaining bits in the register that are not used by the value. `i32` vs `f32`
-/// has already been mentioned above.
+/// are not compatible either, as 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

diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs
@@ -1544,28 +1544,35 @@ mod prim_ref {}
 ///
 /// The following types are guaranteed to be ABI-compatible:
 ///
-/// - Every type is ABI-compatible with itself.
 /// - `*const T`, `*mut T`, `&T`, `&mut T`, `Box<T>`, `NonNull<T>` are all ABI-compatible with each
 ///   other for all `T`.
-/// - 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` is ABI-compatible with its unique non-1-ZST field (if there is
-///   such a field).
+/// - Any two `fn`/`extern "ABI" fn` types with the same call ABI are ABI-compatible with each
+///   other, independent of the rest of their signature.
+/// - Any two types with size 0 and alignment 1 are ABI-compatible.
+/// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-trivial field, i.e., the
+///   unique field that doesn't have size 0 and alignment 1 (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
 ///   optimization](option/index.html#representation), then `T` and `Option<T>` are ABI-compatible.
+///
+/// Furthermore, ABI compatibility satisfies the following general properties:
+///
+/// - Every type is ABI-compatible with itself.
 /// - If `T1` and `T2` are ABI-compatible, then two `repr(C)` types that only differ because one
 ///   field type was changed from `T1` to `T2` are ABI-compatible.
-/// - ABI-compatibility is symmetric and transitive.
+/// - If `T1` and `T2` are ABI-compatible and `T2` and `T3` are ABI-compatible, then so are `T1` and
+///   `T3` (i.e., ABI-compatibility is transitive).
+/// - If `T1` and `T2` are ABI-compatible, then so are `T2` and `T1` (i.e., ABI-compatibility is
+///   symmetric).
 ///
 /// More signatures can be ABI-compatible on specific targets, but that should not be relied upon
 /// since it is not portable and not a stable guarantee.
 ///
 /// Noteworthy cases of types *not* being ABI-compatible in general are `bool` vs `u8`, and `i32` vs
 /// `u32`: on some targets, the calling conventions for these types differ in terms of what they
 /// guarantee for the remaining bits in the register that are not used by the value. `i32` vs `f32`
-/// has already been mentioned above.
+/// are not compatible either, as 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