compiler: Document AbiAndPrefAlign

1 files changed, 8 insertions, 0 deletions

diff --git a/compiler/rustc_abi/src/lib.rs b/compiler/rustc_abi/src/lib.rs
index be42bc84932..4e27ad0c366 100644
--- a/compiler/rustc_abi/src/lib.rs
+++ b/compiler/rustc_abi/src/lib.rs
@@ -781,6 +781,14 @@ impl Align {
 }
 
 /// A pair of alignments, ABI-mandated and preferred.
+///
+/// The "preferred" alignment is an LLVM concept that is virtually meaningless to Rust code:
+/// it is not exposed semantically to programmers nor can they meaningfully affect it.
+/// The only concern for us is that preferred alignment must not be less than the mandated alignment
+/// and thus in practice the two values are almost always identical.
+///
+/// An example of a rare thing actually affected by preferred alignment is aligning of statics.
+/// It is of effectively no consequence for layout in structs and on the stack.
 #[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
 #[cfg_attr(feature = "nightly", derive(HashStable_Generic))]
 pub struct AbiAndPrefAlign {