doc comments for layout components

diff --git a/src/librustc_target/abi/mod.rs b/src/librustc_target/abi/mod.rs
index 3f44339bf4cc285e78b01382788c15b7ec17dcd8..447487e4fb279d93a165c375a709eb4d92a20e5c 100644 (file)
--- a/src/librustc_target/abi/mod.rs
+++ b/src/librustc_target/abi/mod.rs
@@ -871,8 +871,26 @@ pub fn reserve<C: HasDataLayout>(&self, cx: &C, count: u128) -> Option<(u128, Sc
 
 #[derive(PartialEq, Eq, Hash, Debug, HashStable_Generic)]
 pub struct LayoutDetails {
-    pub variants: Variants,
+    /// Says where the fields are located.
+    /// Primitives and fieldless enums appear as unions without fields.
     pub fields: FieldPlacement,
+
+    /// Encodes information about multi-variant layouts.
+    /// Even with `Multiple` variants, a layout can still have fields! Those are then
+    /// shared between all variants. One of them will be the discriminant,
+    /// but e.g. generators can have more.
+    ///
+    /// A layout-guided recursive descent must first look at all the fields,
+    /// and only then check if this is a multi-variant layout and if so, proceed
+    /// with the active variant.
+    pub variants: Variants,
+
+    /// The `abi` defines how this data is passed between functions, and it defines
+    /// value restrictions via `valid_range`.
+    ///
+    /// Note that this is entirely orthogonal to the recursive structrue defined by
+    /// `variants` and `fields`; for example, `ManuallyDrop<Result<isize, isize>>` has
+    /// `Abi::ScalarPair`! So, having a non-`Aggregate` `abi` should not stop a recursive descent.
     pub abi: Abi,
 
     /// The leaf scalar with the largest number of invalid values