2 files changed, 31 insertions, 5 deletions
diff --git a/llvm/docs/TableGen/LangIntro.rst b/llvm/docs/TableGen/LangIntro.rst
index b77dad07bf0..ea46550ffc0 100644
--- a/llvm/docs/TableGen/LangIntro.rst
+++ b/llvm/docs/TableGen/LangIntro.rst
@@ -152,8 +152,8 @@ supported include:
 ``foreach <var> = [ <list> ] in <def>``
     Replicate <body> or <def>, replacing instances of <var> with each value
     in <list>.  <var> is scoped at the level of the ``foreach`` loop and must
-    not conflict with any other object introduced in <body> or <def>.  Currently
-    only ``def``\s are expanded within <body>.
+    not conflict with any other object introduced in <body> or <def>.  Only
+    ``def``\s and ``defm``\s are expanded within <body>.
 
 ``foreach <var> = 0-15 in ...``
 
@@ -348,6 +348,23 @@ In this case, the ``Z`` definition will have a zero value for its ``V`` value,
 despite the fact that it derives (indirectly) from the ``C`` class, because the
 ``D`` class overrode its value.
 
+References between variables in a record are substituted late, which gives
+``let`` expressions unusual power. Consider this admittedly silly example:
+
+.. code-block:: text
+
+  class A<int x> {
+    int Y = x;
+    int Yplus1 = !add(Y, 1);
+    int xplus1 = !add(x, 1);
+  }
+  def Z : A<5> {
+    let Y = 10;
+  }
+
+The value of ``Z.xplus1`` will be 6, but the value of ``Z.Yplus1`` is 11. Use
+this power wisely.
+
 .. _template arguments:
 
 Class template arguments
diff --git a/llvm/docs/TableGen/LangRef.rst b/llvm/docs/TableGen/LangRef.rst
index d31f7f36c80..439d646034a 100644
--- a/llvm/docs/TableGen/LangRef.rst
+++ b/llvm/docs/TableGen/LangRef.rst
@@ -229,15 +229,17 @@ of:
        int Baz = Bar;
      }
 
+  Values defined in superclasses can be accessed the same way.
+
 * a template arg of a ``class``, such as the use of ``Bar`` in::
 
      class Foo<int Bar> {
        int Baz = Bar;
      }
 
-* value local to a ``multiclass``, such as the use of ``Bar`` in::
+* value local to a ``class``, such as the use of ``Bar`` in::
 
-     multiclass Foo {
+     class Foo {
        int Bar = 5;
        int Baz = Bar;
      }
@@ -245,9 +247,16 @@ of:
 * a template arg to a ``multiclass``, such as the use of ``Bar`` in::
 
      multiclass Foo<int Bar> {
-       int Baz = Bar;
+       def : SomeClass<Bar>;
      }
 
+* the iteration variable of a ``foreach``, such as the use of ``i`` in::
+
+     foreach i = 0-5 in
+     def Foo#i;
+
+* a variable defined by ``defset``
+
 * the implicit template argument ``NAME`` in a ``class`` or ``multiclass``
 
 .. productionlist::