Rollup merge of #130384 - workingjubilee:document-what-abi-and-pref-a…

…lign-is, r=compiler-errors

compiler: Document AbiAndPrefAlign

The mere existence of this struct is confusing, and the second field doubly so. It's easy to mistake the "preferred" alignment as semantically relevant somehow. Insofar as I am aware, it is not, and certainly not for Rust code.

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 {