[llvm] 6a067cd - [TableGen] [docs] Improve description of NAME in Programmer's Reference

[Paul C. Anagnostopoulos via llvm-commits]

Author: Paul C. Anagnostopoulos
Date: 2021-04-23T09:49:17-04:00
New Revision: 6a067cdb06a0d7afd2d74ec7303a97403bc096ec

URL: https://github.com/llvm/llvm-project/commit/6a067cdb06a0d7afd2d74ec7303a97403bc096ec
DIFF: https://github.com/llvm/llvm-project/commit/6a067cdb06a0d7afd2d74ec7303a97403bc096ec.diff

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

Also use "parent class" consistently and add a note about the term.

Differential Revision: https://reviews.llvm.org/D100867

Added: 
    

Modified: 
    llvm/docs/TableGen/ProgRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/TableGen/ProgRef.rst b/llvm/docs/TableGen/ProgRef.rst
index c9bee3fa31bb0..852aab9264b7a 100644
--- a/llvm/docs/TableGen/ProgRef.rst
+++ b/llvm/docs/TableGen/ProgRef.rst
@@ -15,7 +15,7 @@ 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.
@@ -62,12 +62,19 @@ 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 arises 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
@@ -86,10 +93,10 @@ 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 
diff erent set of arguments. Without template
 arguments, many more classes would be required, one for each combination of
 the template arguments.
@@ -474,12 +481,11 @@ See `Using Classes as Subroutines`_ for more information.
    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
@@ -571,7 +577,7 @@ 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``.
@@ -594,8 +600,8 @@ their declarations are parsed, and thus before the class is finally defined.
 
 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.
 
@@ -605,7 +611,7 @@ 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.
 
@@ -633,9 +639,9 @@ 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
@@ -659,12 +665,13 @@ 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.
@@ -678,8 +685,8 @@ 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
 
@@ -719,7 +726,7 @@ 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.
@@ -731,7 +738,7 @@ 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
 
@@ -750,8 +757,8 @@ class is specified as a superclass of another class or record.
 
 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.
@@ -835,7 +842,7 @@ in braces or a single statement with no braces. The bindings in the
 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
@@ -869,7 +876,7 @@ themselves.
 
 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
@@ -891,22 +898,22 @@ 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.
 
@@ -915,7 +922,7 @@ See `Examples: multiclasses and defms`_ for examples.
 -----------------------------------------------------------
 
 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.
 
@@ -935,8 +942,8 @@ 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 
diff erent names::
+not included, an unspecified but globally unique name is provided. That is,
+the following examples end up with 
diff erent names::
 
     defm    : SomeMultiClass<...>;   // A globally unique name.
     defm "" : SomeMultiClass<...>;   // An empty name.
@@ -951,8 +958,8 @@ 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.
 
@@ -1372,12 +1379,12 @@ 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.
@@ -1605,7 +1612,7 @@ and non-0 as true.
 
     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
@@ -1976,8 +1983,8 @@ register-to-register ADD instruction.
 
 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: