[TableGen] [docs] Improve description of NAME in Programmer's Reference

[Paul-C-Anagnostopoulos]

Summary

This revision improves the description of the implicit template argument NAME in the TableGen "Programmer's Reference."

It also uses the term "parent class" consistently.

[dblaikie]

llvm/docs/TableGen/ProgRef.rst

65–67

Not sure how the wording is used in other parts of the TableGen docs, but since LLVM's a C++ oriented project, maybe we should standardize/lean towards the C++ terminology as being the canonical one, which would be "base" class?

[Paul-C-Anagnostopoulos]

llvm/docs/TableGen/ProgRef.rst

65–67

Here we are talking about a record inheriting from a class. I can't find any standard name for that class. Is "base class" the standard? As far as I can tell, "base," "parent," and "super" all pertain to the class hierarchy.

[dblaikie]

llvm/docs/TableGen/ProgRef.rst

65–67

In the C++ standard "base" is the term that's used - that's visible also in the C++ API with type traits like std::is_base_of ( https://en.cppreference.com/w/cpp/types/is_base_of )

[Paul-C-Anagnostopoulos]

llvm/docs/TableGen/ProgRef.rst

65–67

std::is_base_of() takes two classes. Here we need a term for the class that a record inherits from, not a term involving the class hierarchy. In C++ we would be talking about an instance's class, for which the term is just "class." But we don't think of records as instances.

I suppose "base class" is just as good as "parent class" and would be the correct term when we are talking about one class inheriting from another class. Okay, let me reword the text with "base class" as the primary term.

[dblaikie]

llvm/docs/TableGen/ProgRef.rst

65–67

Here we need a term for the class that a record inherits from,

Hmm, OK - maybe there isn't a good analogy with C++, then.

What if the wording here said "an optional list of classes" (rather than base/parent/super)? I guess that doesn't apply to all the other places.

I guess: How'd you pick parent rather than super or base (but not completely consistently)? Were there more uses of parent than any other, so you decided to standardize on that name?

[Paul-C-Anagnostopoulos]

llvm/docs/TableGen/ProgRef.rst

65–67

Yes, I tried to go with the more common term. But I also avoided superclass, which really suggests a class-to-class relationship.

[Paul-C-Anagnostopoulos]

The more I think about it, the more I like "parent class" rather than "base class." It's the only term that seems like it could apply to a record's class. Let me look at the uses and see if some or most can just use the term "class."

[Paul-C-Anagnostopoulos]

I'm going to stick with "parent class," but if there are any sentences that talk only about records, I will try to use just "class." I will add a note at the appropriate spot explaining this.

[dblaikie]

In D100867#2704875, @Paul-C-Anagnostopoulos wrote:

I'm going to stick with "parent class," but if there are any sentences that talk only about records, I will try to use just "class." I will add a note at the appropriate spot explaining this.

Fair enough. I wouldn't mind @lattner 's take on this since he's probably got some history & more context with the naming.

[Paul-C-Anagnostopoulos]

I added a note about the term "parent class." It proved futile to try to remove the word "parent" in certain sentences. Many pertain to both classes and records. And those that don't just seemed to become inconsistent when I tried to remove the word.

llvm/docs/TableGen/ProgRef.rst

 Introduction
 ============
 
 The purpose of TableGen is to generate complex output files based on
 information from source files that are significantly easier to code than the
 output files would be, and also easier to maintain and modify over time. The
 information is coded in a declarative style involving classes and records,
 which are then processed by TableGen. The internalized records are passed on
-to various backends, which extract information from a subset of the records
+to various *backends*, which extract information from a subset of the records
 and generate one or more output files. These output files are typically
 ``.inc`` files for C++, but may be any type of file that the backend
 developer needs.
 
 This document describes the LLVM TableGen facility in detail. It is intended
 for the programmer who is using TableGen to produce code for a project. If
 you are looking for a simple overview, check out the :doc:`TableGen Overview
 <./index>`.  The various ``*-tblgen`` commands used to invoke TableGen are

 *concrete records*. In this and other TableGen documents, abstract records
 are called *classes.* (These classes are different from C++ classes and do
 not map onto them.) In addition, concrete records are usually just called
 records, although sometimes the term *record* refers to both classes and
 concrete records. The distinction should be clear in context.
 
 Classes and concrete records have a unique *name*, either chosen by
 the programmer or generated by TableGen. Associated with that name
-is a list of *fields* with values and an optional list of *superclasses*
-(sometimes called base or parent classes). The fields are the primary data that
+is a list of *fields* with values and an optional list of *parent classes*
+(sometimes called base or super classes). The fields are the primary data that
 backends will process. Note that TableGen assigns no meanings to fields; the
 meanings are entirely up to the backends and the programs that incorporate
 the output of those backends.
 
+.. note::
+
+  The term "parent class" can refer to a class that is a parent of another
+  class, and also to a class from which a concrete record inherits. This
+  nonstandard use of the term occurs because TableGen treats classes and
+  concrete records similarly.
+
 A backend processes some subset of the concrete records built by the
 TableGen parser and emits the output files. These files are usually C++
 ``.inc`` files that are included by the programs that require the data in
 those records. However, a backend can produce any type of output files. For
 example, it could produce a data file containing messages tagged with
 identifiers and substitution parameters. In a complex use case such as the
 LLVM code generator, there can be many concrete records and some of them can
 have an unexpectedly large number of fields, resulting in large output files.
 
 In order to reduce the complexity of TableGen files, classes are used to
 abstract out groups of record fields. For example, a few classes may
 abstract the concept of a machine register file, while other classes may
 abstract the instruction formats, and still others may abstract the
 individual instructions. TableGen allows an arbitrary hierarchy of classes,
 so that the abstract classes for two concepts can share a third superclass that
 abstracts common "sub-concepts" from the two original concepts.
 
 In order to make classes more useful, a concrete record (or another class)
-can request a class as a superclass and pass *template arguments* to it.
-These template arguments can be used in the fields of the superclass to
+can request a class as a parent class and pass *template arguments* to it.
+These template arguments can be used in the fields of the parent class to
 initialize them in a custom manner. That is, record or class ``A`` can
-request superclass ``S`` with one set of template arguments, while record or class
+request parent class ``S`` with one set of template arguments, while record or class
 ``B`` can request ``S`` with a different set of arguments. Without template
 arguments, many more classes would be required, one for each combination of
 the template arguments.
 
 Both classes and concrete records can include fields that are uninitialized.
 The uninitialized "value" is represented by a question mark (``?``). Classes
 often have uninitialized fields that are expected to be filled in when those
 classes are inherited by concrete records. Even so, some fields of concrete

 See `Using Classes as Subroutines`_ for more information.
 
 .. productionlist::
    SimpleValue9: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
               :| `CondOperator` "(" `CondClause` ("," `CondClause`)* ")"
    CondClause: `Value` ":" `Value`
 
 The bang operators provide functions that are not available with the other
-simple values. Except in the case of ``!cond``, a bang
-operator takes a list of arguments enclosed in parentheses and performs some
-function on those arguments, producing a value for that
-bang operator. The ``!cond`` operator takes a list of pairs of arguments
-separated by colons. See `Appendix A: Bang Operators`_ for a description of
-each bang operator.
+simple values. Except in the case of ``!cond``, a bang operator takes a list
+of arguments enclosed in parentheses and performs some function on those
+arguments, producing a value for that bang operator. The ``!cond`` operator
+takes a list of pairs of arguments separated by colons. See `Appendix A:
+Bang Operators`_ for a description of each bang operator.
 
 
 Suffixed values
 ---------------
 
 The :token:`SimpleValue` values described above can be specified with
 certain suffixes. The purpose of a suffix is to obtain a subvalue of the
 primary value. Here are the possible suffixes for some primary *value*.

 uninitialized (has the "value" ``?``) and must be specified in the template
 argument list when the class is inherited (required argument). If an
 argument is assigned a default value, then it need not be specified in the
 argument list (optional argument). In the declaration, all required template
 arguments must precede any optional arguments. The template argument default
 values are evaluated from left to right.
 
 The :token:`RecordBody` is defined below. It can include a list of
-superclasses from which the current class inherits, along with field
+parent classes from which the current class inherits, along with field
 definitions and other statements. When a class ``C`` inherits from another
 class ``D``, the fields of ``D`` are effectively merged into the fields of
 ``C``.
 
 A given class can only be defined once. A ``class`` statement is
 considered to define the class if *any* of the following are true (the
 :token:`RecordBody` elements are described below).
 
 * The :token:`TemplateArgList` is present, or
 * The :token:`ParentClassList` in the :token:`RecordBody` is present, or
 * The :token:`Body` in the :token:`RecordBody` is present and not empty.
 
 You can declare an empty class by specifying an empty :token:`TemplateArgList`
 and an empty :token:`RecordBody`. This can serve as a restricted form of
 forward declaration. Note that records derived from a forward-declared
 class will inherit no fields from it, because those records are built when
 their declarations are parsed, and thus before the class is finally defined.
 
 .. _NAME:
 
 Every class has an implicit template argument named ``NAME`` (uppercase),
 which is bound to the name of the :token:`Def` or :token:`Defm` inheriting
-the class. The value of ``NAME`` is undefined if the class is inherited by
-an anonymous record.
+from the class. If the class is inherited by an anonymous record, the name
+is unspecified but globally unique.
 
 See `Examples: classes and records`_ for examples.
 
 Record Bodies
 `````````````
 
 Record bodies appear in both class and record definitions. A record body can
 include a parent class list, which specifies the classes from which the
 current class or record inherits fields. Such classes are called the
-superclasses or parent classes of the class or record. The record body also
+parent classes of the class or record. The record body also
 includes the main body of the definition, which contains the specification
 of the fields of the class or record.
 
 .. productionlist::
    RecordBody: `ParentClassList` `Body`
    ParentClassList: [":" `ParentClassListNE`]
    ParentClassListNE: `ClassRef` ("," `ClassRef`)*
    ClassRef: (`ClassID` | `MultiClassID`) ["<" [`ValueList`] ">"]

 
 A field definition in the body specifies a field to be included in the class
 or record. If no initial value is specified, then the field's value is
 uninitialized. The type must be specified; TableGen will not infer it from
 the value. The keyword ``code`` may be used to emphasize that the field
 has a string value that is code.
 
 The ``let`` form is used to reset a field to a new value. This can be done
-for fields defined directly in the body or fields inherited from
-superclasses.  A :token:`RangeList` can be specified to reset certain bits
-in a ``bit<n>`` field.
+for fields defined directly in the body or fields inherited from parent
+classes.  A :token:`RangeList` can be specified to reset certain bits in a
+``bit<n>`` field.
 
 The ``defvar`` form defines a variable whose value can be used in other
 value expressions within the body. The variable is not a field: it does not
 become a field of the class or record being defined. Variables are provided
 to hold temporary values while processing the body. See `Defvar in a Record
 Body`_ for more details.
 
 When class ``C2`` inherits from class ``C1``, it acquires all the field
 definitions of ``C1``. As those definitions are merged into class ``C2``, any
 template arguments passed to ``C1`` by ``C2`` are substituted into the
 definitions. In other words, the abstract record fields defined by ``C1`` are
 expanded with the template arguments before being merged into ``C2``.
 
 
 .. _def:
 
 ``def`` --- define a concrete record
 ------------------------------------
 
 A ``def`` statement defines a new concrete record.
 
 .. productionlist::
    Def: "def" [`NameValue`] `RecordBody`
-   NameValue: `Value` (parsed in a special manner)
+   NameValue: `Value` (parsed in a special mode)
 
 The name value is optional. If specified, it is parsed in a special mode
 where undefined (unrecognized) identifiers are interpreted as literal
 strings. In particular, global identifiers are considered unrecognized.
-These include global variables defined by ``defvar`` and ``defset``.
+These include global variables defined by ``defvar`` and ``defset``. A
+record name can be the null string.
 
 If no name value is given, the record is *anonymous*. The final name of an
 anonymous record is unspecified but globally unique.
 
 Special handling occurs if a ``def`` appears inside a ``multiclass``
 statement. See the ``multiclass`` section below for details.
 
 A record can inherit from one or more classes by specifying the
 :token:`ParentClassList` clause at the beginning of its record body. All of
 the fields in the parent classes are added to the record. If two or more
 parent classes provide the same field, the record ends up with the field value
 of the last parent class.
 
-As a special case, the name of a record can be passed in a template argument
-to that record's superclasses. For example:
+As a special case, the name of a record can be passed as a template argument
+to that record's parent classes. For example:
 
 .. code-block:: text
 
   class A <dag d> {
     dag the_dag = d;
   }
 
   def rec1 : A<(ops rec1)>
def Y : C {
     let V = false;
     string Greeting = "Hello!";
   }
 
 First, the abstract class ``C`` is defined. It has one field named ``V``
 that is a bit initialized to true.
 
 Next, two records are defined, derived from class ``C``; that is, with ``C``
-as their superclass. Thus they both inherit the ``V`` field. Record ``Y``
+as their parent class. Thus they both inherit the ``V`` field. Record ``Y``
 also defines another string field, ``Greeting``, which is initialized to
 ``"Hello!"``. In addition, ``Y`` overrides the inherited ``V`` field,
 setting it to false.
 
 A class is useful for isolating the common features of multiple records in
 one place. A class can initialize common fields to default values, but
 records inheriting from that class can override the defaults.
 
 TableGen supports the definition of parameterized classes as well as
 nonparameterized ones. Parameterized classes specify a list of variable
 declarations, which may optionally have defaults, that are bound when the
-class is specified as a superclass of another class or record.
+class is specified as a parent class of another class or record.
 
 .. code-block:: text
 
   class FPFormat <bits<3> val> {
     bits<3> Value = val;
   }
 
   def NotFP      : FPFormat<0>;
   def ZeroArgFP  : FPFormat<1>;
   def OneArgFP   : FPFormat<2>;
   def OneArgFPRW : FPFormat<3>;
   def TwoArgFP   : FPFormat<4>;
   def CompareFP  : FPFormat<5>;
   def CondMovFP  : FPFormat<6>;
   def SpecialFP  : FPFormat<7>;
 
 The purpose of the ``FPFormat`` class is to act as a sort of enumerated
 type. It provides a single field, ``Value``, which holds a 3-bit number. Its
-template argument, ``val``, is used to set the ``Value`` field.
-Each of the eight records is defined with ``FPFormat`` as its superclass. The
+template argument, ``val``, is used to set the ``Value`` field.  Each of the
+eight records is defined with ``FPFormat`` as its parent class. The
 enumeration value is passed in angle brackets as the template argument. Each
 record will inherent the ``Value`` field with the appropriate enumeration
 value.
 
 Here is a more complex example of classes with template arguments. First, we
 define a class similar to the ``FPFormat`` class above. It takes a template
 argument and uses it to initialize a field named ``Value``. Then we define
 four records that inherit the ``Value`` field with its four different

 
 The ``let`` statement establishes a scope, which is a sequence of statements
 in braces or a single statement with no braces. The bindings in the
 :token:`LetList` apply to the statements in that scope.
 
 The field names in the :token:`LetList` must name fields in classes inherited by
 the classes and records defined in the statements. The field values are
 applied to the classes and records *after* the records inherit all the fields from
-their superclasses. So the ``let`` acts to override inherited field
+their parent classes. So the ``let`` acts to override inherited field
 values. A ``let`` cannot override the value of a template argument.
 
 Top-level ``let`` statements are often useful when a few fields need to be
 overriden in several records. Here are two examples. Note that ``let``
 statements can be nested.
 
 .. code-block:: text
 

 themselves.
 
 
 ``multiclass`` --- define multiple records
 ------------------------------------------
 
 While classes with template arguments are a good way to factor out commonality
 between multiple records, multiclasses allow a convenient method for
-defining multiple records at once. For example, consider a 3-address
+defining many records at once. For example, consider a 3-address
 instruction architecture whose instructions come in two formats: ``reg = reg
 op reg`` and ``reg = reg op imm`` (e.g., SPARC). We would like to specify in
 one place that these two common formats exist, then in a separate place
 specify what all the operations are. The ``multiclass`` and ``defm``
 statements accomplish this goal. You can think of a multiclass as a macro or
 template that expands into multiple records.
 
 .. productionlist::
    MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
              : [":" `ParentMultiClassList`]
              : "{" `Statement`+ "}"
    ParentMultiClassList: `MultiClassID` ("," `MultiClassID`)*
    MultiClassID: `TokIdentifier`
 
 As with regular classes, the multiclass has a name and can accept template
 arguments. A multiclass can inherit from other multiclasses, which causes
 the other multiclasses to be expanded and contribute to the record
 definitions in the inheriting multiclass. The body of the multiclass
 contains a series of statements that define records, using :token:`Def` and
 :token:`Defm`. In addition, :token:`Defvar`, :token:`Foreach`, and
 :token:`Let` statements can be used to factor out even more common elements.
-The :token:`If` statement can also be used.
+The :token:`If` and :token:`Assert` statements can also be used.
 
 Also as with regular classes, the multiclass has the implicit template
 argument ``NAME`` (see NAME_). When a named (non-anonymous) record is
-defined in a multiclass and the record's name does not contain a use of the
-template argument ``NAME``, such a use is automatically prepended
+defined in a multiclass and the record's name does not include a use of the
+template argument ``NAME``, such a use is automatically *prepended*
 to the name.  That is, the following are equivalent inside a multiclass::
 
     def Foo ...
-    def NAME#Foo ...
+    def NAME # Foo ...
 
-The records defined in a multiclass are instantiated when the multiclass is
+The records defined in a multiclass are created when the multiclass is
 "instantiated" or "invoked" by a ``defm`` statement outside the multiclass
-definition. Each ``def`` statement produces a record. As with top-level
-``def`` statements, these definitions can inherit from multiple
-superclasses.
+definition. Each ``def`` statement in the multiclass produces a record. As
+with top-level ``def`` statements, these definitions can inherit from
+multiple parent classes.
 
 See `Examples: multiclasses and defms`_ for examples.
 
 
 ``defm`` --- invoke multiclasses to define multiple records
 -----------------------------------------------------------
 
 Once multiclasses have been defined, you use the ``defm`` statement to
-"invoke" multiclasses and process the multiple record definitions in those
+"invoke" them and process the multiple record definitions in those
 multiclasses. Those record definitions are specified by ``def`` 
 statements in the multiclasses, and indirectly by ``defm`` statements.
 
 .. productionlist::
    Defm: "defm" [`NameValue`] `ParentClassList` ";"
 
 The optional :token:`NameValue` is formed in the same way as the name of a
 ``def``. The :token:`ParentClassList` is a colon followed by a list of at
 least one multiclass and any number of regular classes. The multiclasses
 must precede the regular classes. Note that the ``defm`` does not have a
 body.
 
 This statement instantiates all the records defined in all the specified
 multiclasses, either directly by ``def`` statements or indirectly by
 ``defm`` statements. These records also receive the fields defined in any
 regular classes included in the parent class list. This is useful for adding
 a common set of fields to all the records created by the ``defm``.
 
 The name is parsed in the same special mode used by ``def``. If the name is
-not included, a globally unique name is provided. That is, the following
-examples end up with different names::
+not included, an unspecified but globally unique name is provided. That is,
+the following examples end up with different names::
 
     defm    : SomeMultiClass<...>;   // A globally unique name.
     defm "" : SomeMultiClass<...>;   // An empty name.
 
 The ``defm`` statement can be used in a multiclass body. When this occurs,
 the second variant is equivalent to::
 
   defm NAME : SomeMultiClass<...>;
 
 More generally, when ``defm`` occurs in a multiclass and its name does not
 include a use of the implicit template argument ``NAME``, then ``NAME`` will
 be prepended automatically. That is, the following are equivalent inside a
 multiclass::
 
-    defm Foo      : SomeMultiClass<...>;
-    defm NAME#Foo : SomeMultiClass<...>;
+    defm Foo        : SomeMultiClass<...>;
+    defm NAME # Foo : SomeMultiClass<...>;
 
 See `Examples: multiclasses and defms`_ for examples.
 
 Examples: multiclasses and defms
 --------------------------------
 
 Here is a simple example using ``multiclass`` and ``defm``.  Consider a
 3-address instruction architecture whose instructions come in two formats:

 How records are built
 ---------------------
 
 The following steps are taken by TableGen when a record is built. Classes are simply
 abstract records and so go through the same steps.
 
 1. Build the record name (:token:`NameValue`) and create an empty record.
 
-2. Parse the superclasses in the :token:`ParentClassList` from left to
-   right, visiting each superclass's ancestor classes from top to bottom.
+2. Parse the parent classes in the :token:`ParentClassList` from left to
+   right, visiting each parent class's ancestor classes from top to bottom.
 
-  a. Add the fields from the superclass to the record.
+  a. Add the fields from the parent class to the record.
   b. Substitute the template arguments into those fields.
-  c. Add the superclass to the record's list of inherited classes.
+  c. Add the parent class to the record's list of inherited classes.
 
 3. Apply any top-level ``let`` bindings to the record. Recall that top-level
    bindings only apply to inherited fields.
 
 4. Parse the body of the record.
 
   * Add any fields to the record.
   * Modify the values of fields according to local ``let`` statements.

 ``!dag(``\ *op*\ ``,`` *arguments*\ ``,`` *names*\ ``)``
     This operator creates a DAG node with the given operator and
     arguments. The *arguments* and *names* arguments must be lists
     of equal length or uninitialized (``?``). The *names* argument
     must be of type ``list<string>``.
 
     Due to limitations of the type system, *arguments* must be a list of items
     of a common type. In practice, this means that they should either have the
-    same type or be records with a common superclass. Mixing ``dag`` and
+    same type or be records with a common parent class. Mixing ``dag`` and
     non-``dag`` items is not possible. However, ``?`` can be used.
 
     Example: ``!dag(op, [a1, a2, ?], ["name1", "name2", "name3"])`` results in
     ``(op a1-value:$name1, a2-value:$name2, ?:$name3)``.
 
 ``!empty(``\ *a*\ ``)``
     This operator produces 1 if the string, list, or DAG *a* is empty; 0 otherwise.
     A dag is empty if it has no arguments; the operator does not count.
def ADD32rr { // InstructionEncoding Instruction X86Inst I ITy Sched BinOpRR BinOpRR_RF
     string FoldGenRegForm = ?;
     string EVEX2VEXOverride = ?;
     bit isMemoryFoldable = 1;
     bit notEVEX2VEXConvertible = 0;
   }
 
 On the first line of the record, you can see that the ``ADD32rr`` record
 inherited from eight classes. Although the inheritance hierarchy is complex,
-using superclasses is much simpler than specifying the 109 individual fields for each
-instruction.
+using parent classes is much simpler than specifying the 109 individual
+fields for each instruction.
 
 Here is the code fragment used to define ``ADD32rr`` and multiple other
 ``ADD`` instructions:
 
 .. code-block:: text
 
   defm ADD : ArithBinOp_RF<0x00, 0x02, 0x04, "add", MRM0r, MRM0m,
                            X86add_flag, add, 1, 1, 1>;
 
 The ``defm`` statement tells TableGen that ``ArithBinOp_RF`` is a
 multiclass, which contains multiple concrete record definitions that inherit
 from ``BinOpRR_RF``. That class, in turn, inherits from ``BinOpRR``, which
 inherits from ``ITy`` and ``Sched``, and so forth. The fields are inherited
 from all the parent classes; for example, ``IsIndirectBranch`` is inherited
 from the ``Instruction`` class.