[TableGen] Update documents to make them more complete

[Paul-C-Anagnostopoulos]

Summary

This patch updates some TableGen documents to make them more complete, fix a few typos, and add cross-references between the documents.

I will auto-LGTM this after 24 hours.

[nhaehnle]

LGTM

llvm/docs/TableGen/BackEnds.rst

 
 Clang, on the other hand, uses it mainly for diagnostic messages (errors,
 warnings, tips) and attributes, so more on the textual end of the scale.
 
 MLIR uses TableGen to define operations, operation dialects, and operation
 traits.
 
 See the :doc:`TableGen Programmer's Reference <./ProgRef>` for an in-depth
-description of TableGen, and :doc:`TableGen Backend Developer's Guide
+description of TableGen, and the :doc:`TableGen Backend Developer's Guide
 <./BackGuide>` for a guide to writing a new backend.
 
 LLVM BackEnds
 =============
 
 .. warning::
-   This document is raw. Each section below needs three sub-sections: description
-   of its purpose with a list of users, output generated from generic input, and
-   finally why it needed a new backend (in case there's something similar).
+   This portion is incomplete. Each section below needs three subsections:
+   description of its purpose with a list of users, output generated from
+   generic input, and finally why it needed a new backend (in case there's
+   something similar).
 
 Overall, each backend will take the same TableGen file type and transform into
 similar output for different targets/uses. There is an implicit contract between
 the TableGen files, the back-ends and their users.
 
 For instance, a global contract is that each back-end produces macro-guarded
 sections. Based on whether the file is included by a header or a source file,
 or even in which context of each file the include is being used, you have

 --------
 
 **Purpose**: Creates ``AttributeReference.rst`` from ``AttrDocs.td``, and is
 used for documenting user-facing attributes.
 
 General BackEnds
 ================
 
+Print Records
+-------------
+
+The TableGen command option ``--print-records`` invokes a simple backend
+that prints all the classes and records defined in the source files. This is
+the default backend option. See the :doc:`TableGen Backend Developer's Guide
+<./BackGuide>` for more information.
+
+Print Detailed Records
+----------------------
+
+The TableGen command option ``--print-detailed-records`` invokes a backend
+that prints all the global variables, classes, and records defined in the
+source files, with more detail than the default record printer. See the
+:doc:`TableGen Backend Developer's Guide <./BackGuide>` for more
+information.
+
+JSON Reference
+--------------
+
+**Purpose**: Output all the values in every ``def``, as a JSON data
+structure that can be easily parsed by a variety of languages. Useful
+for writing custom backends without having to modify TableGen itself,
+or for performing auxiliary analysis on the same TableGen data passed
+to a built-in backend.
+
+**Output**:
+
+The root of the output file is a JSON object (i.e. dictionary),
+containing the following fixed keys:
+
+* ``!tablegen_json_version``: a numeric version field that will
+  increase if an incompatible change is ever made to the structure of
+  this data. The format described here corresponds to version 1.
+
+* ``!instanceof``: a dictionary whose keys are the class names defined
+  in the TableGen input. For each key, the corresponding value is an
+  array of strings giving the names of ``def`` records that derive
+  from that class. So ``root["!instanceof"]["Instruction"]``, for
+  example, would list the names of all the records deriving from the
+  class ``Instruction``.
+
+For each ``def`` record, the root object also has a key for the record
+name. The corresponding value is a subsidiary object containing the
+following fixed keys:
+
+* ``!superclasses``: an array of strings giving the names of all the
+  classes that this record derives from.
+
+* ``!fields``: an array of strings giving the names of all the variables
+  in this record that were defined with the ``field`` keyword.
+
+* ``!name``: a string giving the name of the record. This is always
+  identical to the key in the JSON root object corresponding to this
+  record's dictionary. (If the record is anonymous, the name is
+  arbitrary.)
+
+* ``!anonymous``: a boolean indicating whether the record's name was
+  specified by the TableGen input (if it is ``false``), or invented by
+  TableGen itself (if ``true``).
+
+For each variable defined in a record, the ``def`` object for that
+record also has a key for the variable name. The corresponding value
+is a translation into JSON of the variable's value, using the
+conventions described below.
+
+Some TableGen data types are translated directly into the
+corresponding JSON type:
+
+* A completely undefined value (e.g. for a variable declared without
+  initializer in some superclass of this record, and never initialized
+  by the record itself or any other superclass) is emitted as the JSON
+  ``null`` value.
+
+* ``int`` and ``bit`` values are emitted as numbers. Note that
+  TableGen ``int`` values are capable of holding integers too large to
+  be exactly representable in IEEE double precision. The integer
+  literal in the JSON output will show the full exact integer value.
+  So if you need to retrieve large integers with full precision, you
+  should use a JSON reader capable of translating such literals back
+  into 64-bit integers without losing precision, such as Python's
+  standard ``json`` module.
+
+* ``string`` and ``code`` values are emitted as JSON strings.
+
+* ``list<T>`` values, for any element type ``T``, are emitted as JSON
+  arrays. Each element of the array is represented in turn using these
+  same conventions.
+
+* ``bits`` values are also emitted as arrays. A ``bits`` array is
+  ordered from least-significant bit to most-significant. So the
+  element with index ``i`` corresponds to the bit described as
+  ``x{i}`` in TableGen source. However, note that this means that
+  scripting languages are likely to *display* the array in the
+  opposite order from the way it appears in the TableGen source or in
+  the diagnostic ``-print-records`` output.
+
+All other TableGen value types are emitted as a JSON object,
+containing two standard fields: ``kind`` is a discriminator describing
+which kind of value the object represents, and ``printable`` is a
+string giving the same representation of the value that would appear
+in ``-print-records``.
+
+* A reference to a ``def`` object has ``kind=="def"``, and has an
+  extra field ``def`` giving the name of the object referred to.
+
+* A reference to another variable in the same record has
+  ``kind=="var"``, and has an extra field ``var`` giving the name of
+  the variable referred to.
+
+* A reference to a specific bit of a ``bits``-typed variable in the
+  same record has ``kind=="varbit"``, and has two extra fields:
+  ``var`` gives the name of the variable referred to, and ``index``
+  gives the index of the bit.
+
+* A value of type ``dag`` has ``kind=="dag"``, and has two extra
+  fields. ``operator`` gives the initial value after the opening
+  parenthesis of the dag initializer; ``args`` is an array giving the
+  following arguments. The elements of ``args`` are arrays of length
+  2, giving the value of each argument followed by its colon-suffixed
+  name (if any). For example, in the JSON representation of the dag
+  value ``(Op 22, "hello":$foo)`` (assuming that ``Op`` is the name of
+  a record defined elsewhere with a ``def`` statement):
+
+  * ``operator`` will be an object in which ``kind=="def"`` and
+    ``def=="Op"``
+
+  * ``args`` will be the array ``[[22, null], ["hello", "foo"]]``.
+
+* If any other kind of value or complicated expression appears in the
+  output, it will have ``kind=="complex"``, and no additional fields.
+  These values are not expected to be needed by backends. The standard
+  ``printable`` field can be used to extract a representation of them
+  in TableGen source syntax if necessary.
+
 SearchableTables Reference
 --------------------------
 
 A TableGen include file, ``SearchableTable.td``, provides classes for
 generating C++ searchable tables. These tables are described in the
 following sections. To generate the C++ code, run ``llvm-tblgen`` with the
 ``--gen-searchable-tables`` option, which invokes the backend that generates
 the tables from the records you provide.
const CEntry *lookupCEntryByName(StringRef Name, unsigned Kind) {
 
     if (Idx == Table.end() ||
         Key.Name != Idx->Name ||
         Key.Kind != Idx->Kind)
       return nullptr;
     return &CTable[Idx->_index];
   }
 
-JSON
-----
-
-**Purpose**: Output all the values in every ``def``, as a JSON data
-structure that can be easily parsed by a variety of languages. Useful
-for writing custom backends without having to modify TableGen itself,
-or for performing auxiliary analysis on the same TableGen data passed
-to a built-in backend.
-
-**Output**:
-
-The root of the output file is a JSON object (i.e. dictionary),
-containing the following fixed keys:
-
-* ``!tablegen_json_version``: a numeric version field that will
-  increase if an incompatible change is ever made to the structure of
-  this data. The format described here corresponds to version 1.
-
-* ``!instanceof``: a dictionary whose keys are the class names defined
-  in the TableGen input. For each key, the corresponding value is an
-  array of strings giving the names of ``def`` records that derive
-  from that class. So ``root["!instanceof"]["Instruction"]``, for
-  example, would list the names of all the records deriving from the
-  class ``Instruction``.
-
-For each ``def`` record, the root object also has a key for the record
-name. The corresponding value is a subsidiary object containing the
-following fixed keys:
-
-* ``!superclasses``: an array of strings giving the names of all the
-  classes that this record derives from.
-
-* ``!fields``: an array of strings giving the names of all the variables
-  in this record that were defined with the ``field`` keyword.
-
-* ``!name``: a string giving the name of the record. This is always
-  identical to the key in the JSON root object corresponding to this
-  record's dictionary. (If the record is anonymous, the name is
-  arbitrary.)
-
-* ``!anonymous``: a boolean indicating whether the record's name was
-  specified by the TableGen input (if it is ``false``), or invented by
-  TableGen itself (if ``true``).
-
-For each variable defined in a record, the ``def`` object for that
-record also has a key for the variable name. The corresponding value
-is a translation into JSON of the variable's value, using the
-conventions described below.
-
-Some TableGen data types are translated directly into the
-corresponding JSON type:
-
-* A completely undefined value (e.g. for a variable declared without
-  initializer in some superclass of this record, and never initialized
-  by the record itself or any other superclass) is emitted as the JSON
-  ``null`` value.
-
-* ``int`` and ``bit`` values are emitted as numbers. Note that
-  TableGen ``int`` values are capable of holding integers too large to
-  be exactly representable in IEEE double precision. The integer
-  literal in the JSON output will show the full exact integer value.
-  So if you need to retrieve large integers with full precision, you
-  should use a JSON reader capable of translating such literals back
-  into 64-bit integers without losing precision, such as Python's
-  standard ``json`` module.
-
-* ``string`` and ``code`` values are emitted as JSON strings.
-
-* ``list<T>`` values, for any element type ``T``, are emitted as JSON
-  arrays. Each element of the array is represented in turn using these
-  same conventions.
-
-* ``bits`` values are also emitted as arrays. A ``bits`` array is
-  ordered from least-significant bit to most-significant. So the
-  element with index ``i`` corresponds to the bit described as
-  ``x{i}`` in TableGen source. However, note that this means that
-  scripting languages are likely to *display* the array in the
-  opposite order from the way it appears in the TableGen source or in
-  the diagnostic ``-print-records`` output.
-
-All other TableGen value types are emitted as a JSON object,
-containing two standard fields: ``kind`` is a discriminator describing
-which kind of value the object represents, and ``printable`` is a
-string giving the same representation of the value that would appear
-in ``-print-records``.
-
-* A reference to a ``def`` object has ``kind=="def"``, and has an
-  extra field ``def`` giving the name of the object referred to.
-
-* A reference to another variable in the same record has
-  ``kind=="var"``, and has an extra field ``var`` giving the name of
-  the variable referred to.
-
-* A reference to a specific bit of a ``bits``-typed variable in the
-  same record has ``kind=="varbit"``, and has two extra fields:
-  ``var`` gives the name of the variable referred to, and ``index``
-  gives the index of the bit.
-
-* A value of type ``dag`` has ``kind=="dag"``, and has two extra
-  fields. ``operator`` gives the initial value after the opening
-  parenthesis of the dag initializer; ``args`` is an array giving the
-  following arguments. The elements of ``args`` are arrays of length
-  2, giving the value of each argument followed by its colon-suffixed
-  name (if any). For example, in the JSON representation of the dag
-  value ``(Op 22, "hello":$foo)`` (assuming that ``Op`` is the name of
-  a record defined elsewhere with a ``def`` statement):
-
-  * ``operator`` will be an object in which ``kind=="def"`` and
-    ``def=="Op"``
-
-  * ``args`` will be the array ``[[22, null], ["hello", "foo"]]``.
-
-* If any other kind of value or complicated expression appears in the
-  output, it will have ``kind=="complex"``, and no additional fields.
-  These values are not expected to be needed by backends. The standard
-  ``printable`` field can be used to extract a representation of them
-  in TableGen source syntax if necessary.

llvm/docs/TableGen/BackGuide.rst

 This document is a guide to writing a backend for TableGen. It is not a
 complete reference manual, but rather a guide to using the facilities
 provided by TableGen for the backends. For a complete reference to the
 various data structures and functions involved, see the primary TableGen
 header file (``record.h``) and/or the Doxygen documentation.
 
 This document assumes that you have read the :doc:`TableGen Programmer's
 Reference <./ProgRef>`, which provides a detailed reference for coding
-TableGen source files. This document and the relevant Doxygen pages will be
+TableGen source files. This document and the data structure comments will be
 improved over time.
 
 Data Structures
 ===============
 
 The following sections describe the data structures that contain the classes
 and records that are collected from the TableGen source files by the
 TableGen parser. Note that the term *class* refers to an abstract record

llvm/docs/TableGen/index.rst

 
 
 .. _backend:
 .. _backends:
 
 TableGen backends
 =================
 
-TableGen files have no real meaning without a back-end. The default operation
-of running ``llvm-tblgen`` is to print the information in a textual format, but
-that's only useful for debugging of the TableGen files themselves. The power
+TableGen files have no real meaning without a backend. The default operation
+when running ``xxx-tblgen`` is to print the information in a textual format, but
+that's only useful for debugging the TableGen files themselves. The power
 in TableGen is, however, to interpret the source files into an internal 
 representation that can be generated into anything you want.
 
 Current usage of TableGen is to create huge include files with tables that you
 can either include directly (if the output is in the language you're coding),
 or be used in pre-processing via macros surrounding the include of the file.
 
-Direct output can be used if the back-end already prints a table in C format
+Direct output can be used if the backend already prints a table in C format
 or if the output is just a list of strings (for error and warning messages).
 Pre-processed output should be used if the same information needs to be used
-in different contexts (like Instruction names), so your back-end should print
+in different contexts (like Instruction names), so your backend should print
 a meta-information list that can be shaped into different compile-time formats.
 
 See :doc:`TableGen BackEnds <./BackEnds>` for a list of available
 backends, and see the :doc:`TableGen Backend Developer's Guide <./BackGuide>`
-for information on how to write a new backend.
+for information on how to write and debug a new backend.
 
 TableGen Deficiencies
 =====================
 
 Despite being very generic, TableGen has some deficiencies that have been
 pointed out numerous times. The common theme is that, while TableGen allows
 you to build Domain-Specific-Languages, the final languages that you create
 lack the power of other DSLs, which in turn increase considerably the size
 and complexity of TableGen files.
 
 At the same time, TableGen allows you to create virtually any meaning of
-the basic concepts via custom-made back-ends, which can pervert the original
+the basic concepts via custom-made backends, which can pervert the original
 design and make it very hard for newcomers to understand the evil TableGen
 file.
 
 There are some in favour of extending the semantics even more, but making sure
-back-ends adhere to strict rules. Others are suggesting we should move to less,
+backends adhere to strict rules. Others are suggesting we should move to less,
 more powerful DSLs designed with specific purposes, or even re-using existing
 DSLs.
 
 Either way, this is a discussion that will likely span across several years,
 if not decades. You can read more in :doc:`TableGen Deficiencies <./Deficiencies>`.