Added new file & improved inclusivity

[ps-19]

Summary

• Added new file in .md
• Removed .txt file
• Removed mistakes and grammatical error in various files
• Improved Inclusivity to make it beginner-friendly

[xbolva00]

README.md

123

Revert this change here

maypatch.patch

1 ↗

(On Diff #420028)

Remove this file

mlir/docs/Interfaces.md

127

Why?

Please ensure that your corrections are actually correct.

mlir/docs/OpDefinitions.md

3

Strange change

mlir/docs/PassManagement.md

911

hooks ... observe. Seems ok, no?

mlir/docs/README.md

9

Add new line

[ps-19]

This comment was removed by ps-19.

mlir/docs/OpDefinitions.md

3

sorry i think by mistake change had happened. I wrote a program to make certain changes to that might had added some noise.

[xbolva00]

Respected community, i have a question why for all my patches are failing.

No issues in your patch, just CI/CD is not very reliable these days. If found errors are not in the area of your patch, then there are not related to your patch and you can ignore them.

[jpienaar]

Improved Inclusivity to make it beginner-friendly

I'm not sure I see any change related to this.

README.md

3

I'd split this out: this is an LLVM change the rest is specific to MLIR

mlir/docs/LangRef.md

21

This change doesn't make sense.

47

Doesn't make sense.

mlir/docs/PassManagement.md

259

Doesn't make sense

[ps-19]

All mentioned points satisfies now.
@jpienaar

[xbolva00]

mlir/docs/LangRef.md

842

to learn?

mlir/docs/OpDefinitions.md

589

typo

mlir/docs/PDLL.md

33

Wrong?

areas .. exist

mlir/docs/PassManagement.md

42

Nothing wrong with existing line.

131

ne is typo for be

[xbolva00]

Once again, please double check that your corrections are actually correct.

README.md

3

contain seems ok, no?

[mehdi_amini]

README.md

3

contain seemed more correct to me as well?

mlir/README.md

34

I rather not duplicate the website here, why not just pointing there?

[ps-19]

Can anyone please review the differential.

README.md

3

Yes, changes are made in MLIR repository much more than LLVM.

3

As a proof. Both are completely correct, if you think it is not i can edit please give your feedback.

mlir/README.md

1–35

https://reviews.llvm.org/p/jpienaar/ i hope i satisfied your remark.
Thank you.

[aaron.ballman]

README.md

36–38

Removing the extra whitespace is fine, but I don't understand why you removed Clang from the link title. (I think it's more clear with the Clang because it distinguishes it from the LLVM getting started page but maybe you've got a different idea?)

mlir/README.md

34

+1, we should just be able to point the user to the MLIR website, I think.

mlir/docs/LangRef.md

23

I don't think this edit is necessary, but if you wanted to reword this way, it should be "All the different forms describe the same semantic content." to be grammatically correct.

mlir/docs/OpDefinitions.md

214–215

438

584–597

It looks like the numbered lists here are always 1. and that should probably be fixed up.

mlir/docs/README.md

2–9

Why is this file necessary? There's already a README.txt file, and none of the other top-level projects have a README.md

[mehdi_amini]

mlir/docs/README.md

2–9

Note: this is a renaming of .txt to .md.

I think it is there because some people may navigate on GitHub to https://github.com/llvm/llvm-project/tree/main/mlir/docs and the README is what will be rendered there, it provides an opportunity to discourage people from browsing directly there.
It is likely that some GitHub project are designed for the doc to just render well on GitHub

[aaron.ballman]

Most of the changes LGTM, the only concerns I have left are around the READMEs. One thing we could do is split the question about what to do with READMEs off into a separate patch so that we can land the straightforward fixes now, if you'd like.

mlir/docs/README.md

2–9

Note: this is a renaming of .txt to .md.

Thanks, I had missed that!

I think it is there because some people may navigate on GitHub to https://github.com/llvm/llvm-project/tree/main/mlir/docs and the README is what will be rendered there, it provides an opportunity to discourage people from browsing directly there. It is likely that some GitHub project are designed for the doc to just render well on GitHub

That makes sense, but then I think we should be consistent with all of the README.txt files in the repo. WDYT?

[ps-19]

In D122990#3429141, @aaron.ballman wrote:

Most of the changes LGTM, the only concerns I have left are around the READMEs. One thing we could do is split the question about what to do with READMEs off into a separate patch so that we can land the straightforward fixes now, if you'd like.

Sir next i am planning to change all .txt into .md if had some time other than working on a choosen issue.
I am waiting for your feedback weather or not revert that change of .txt -> .md.

mlir/README.md

3

Sir i hope it is fine now.

mlir/docs/README.md

2–9

I have deleted that .txt file.

2–9

From my opinion it is a good practice, else if you say i can restore that change back.

[aaron.ballman]

In D122990#3429176, @ps-19 wrote:

In D122990#3429141, @aaron.ballman wrote:

Most of the changes LGTM, the only concerns I have left are around the READMEs. One thing we could do is split the question about what to do with READMEs off into a separate patch so that we can land the straightforward fixes now, if you'd like.

Sir next i am planning to change all .txt into .md if had some time other than working on a choosen issue.
I am waiting for your feedback weather or not revert that change of .txt -> .md.

I think you should remove the changes to mlir/README.md and revert the rename of mlir/docs/README.txt. Then I think the patch will be ready to land.

Separately, I'd recommend an additional patch that does the rename from README.txt to README.md for the entire monorepo so that all of the projects are handled consistently.

mlir/README.md

3

I think the original content was correct -- it was just a link to the website. What we want to avoid here is duplicating content on the website because then when we change the website, someone has to remember to also change this document (which someone will invariably forget to do, and then we may have conflicting information in two places).

[aaron.ballman]

mlir/README.md

3

I think we want to revert the changes to this file as well.

mlir/docs/README.txt

1

I think this change was unintentional, should probably just revert all changes to the file.

[ps-19]

Minor Changes

[ps-19]

Minor Changes

[ps-19]

Is their anything wrong in this patch?

[mehdi_amini]

mlir/README.md

3

This isn't done, please revert the change to this file entirely.

[aaron.ballman]

LGTM, thank you! When I land, I'll amend the commit message to reflect the changes that happened after you submitted the patch.

[aaron.ballman]

I've commit on your behalf in d356cdcf319ea8123c2ba085bed5d67be8dba176, thank you!

README.md

 # The LLVM Compiler Infrastructure
 
-This directory and its sub-directories contain source code for LLVM,
+This directory and its sub-directories contains the source code for LLVM,
 a toolkit for the construction of highly optimized compilers,
 optimizers, and run-time environments.
 
 The README briefly describes how to get started with building LLVM.
 For more information on how to contribute to the LLVM project, please
 take a look at the
 [Contributing to LLVM](https://llvm.org/docs/Contributing.html) guide.
 

 -- and from there into object files, using LLVM.
 
 Other components include:
 the [libc++ C++ standard library](https://libcxx.llvm.org),
 the [LLD linker](https://lld.llvm.org), and more.
 
 ### Getting the Source Code and Building LLVM
 
-The LLVM Getting Started documentation may be out of date.  The [Clang
-Getting Started](http://clang.llvm.org/get_started.html) page might have more
+The LLVM Getting Started documentation may be out of date.  The Clang
+[Getting Started](http://clang.llvm.org/get_started.html) page might have more
 accurate information.
 
 This is an example work-flow and configuration to get and build the LLVM source:
 
 1. Checkout LLVM (including related sub-projects like Clang):
 
      * ``git clone https://github.com/llvm/llvm-project.git``
 
      * Or, on windows, ``git clone --config core.autocrlf=false
* ``cmake -S llvm -B build -G <generator> [options]``
 
         * The ``check-all`` target (i.e. ``ninja check-all``) will run the
           regression tests to ensure everything is in working order.
 
         * CMake will generate targets for each tool and library, and most
           LLVM sub-projects generate their own ``check-<project>`` target.
 
         * Running a serial build will be **slow**. To improve speed, try running a
-          parallel build.  That's done by default in Ninja; for ``make``, use the option
+          parallel build. That's done by default in Ninja; for ``make``, use the option
           ``-j NNN``, where ``NNN`` is the number of parallel jobs to run.
           In most cases, you get the best performance if you specify the number of CPU threads you have.
           On some Unix systems, you can specify this with ``-j$(nproc)``.
 
       * For more information see [CMake](https://llvm.org/docs/CMake.html).
 
 Consult the
 [Getting Started with LLVM](https://llvm.org/docs/GettingStarted.html#getting-started-with-llvm)
 page for detailed information on configuring and compiling LLVM. You can visit
 [Directory Layout](https://llvm.org/docs/GettingStarted.html#directory-layout)
 to learn about the layout of the source code tree.
 
 ## Getting in touch
 
 Join [LLVM Discourse forums](https://discourse.llvm.org/), [discord chat](https://discord.gg/xS7Z362) or #llvm IRC channel on [OFTC](https://oftc.net/).
 
 The LLVM project has adopted a [code of conduct](https://llvm.org/docs/CodeOfConduct.html) for
 participants to all modes of communication within the project.

mlir/README.md

-# Multi-Level Intermediate Representation
+# Overview
+The MLIR project is a novel approach to building reusable and extensible compiler infrastructure. MLIR aims to address software fragmentation, improve compilation for heterogeneous hardware, significantly reduce the cost of building domain specific compilers, and aid in connecting existing compilers together.
+
+MLIR is a common IR that also supports hardware specific operations. Thus, any investment into the infrastructure surrounding MLIR (e.g. the compiler passes that work on it) should yield good returns; many targets can use that infrastructure and will benefit from it. MLIR is a powerful representation, but it also has non-goals. We do not try to support low level machine code generation algorithms (like register allocation and instruction scheduling). They are a better fit for lower level optimizers (such as LLVM). Also, we do not intend MLIR to be a source language that end-users would themselves write kernels in (analogous to CUDA C++). On the other hand, MLIR provides the backbone for representing any such DSL and integrating it in the ecosystem.
+
+*If you’d like to discuss a particular topic or have questions, please add it to the agenda [doc](https://docs.google.com/document/d/1y_9f1AbfgcoVdJh4_aM6-BaSHvrHl8zuA5G4jv_94K8/edit#). Details on how to join the meeting are in the agenda doc, you can get a Google calendar invite by joining [this](https://groups.google.com/a/tensorflow.org/g/mlir) googlegroup. The meetings are recorded and published in the [talks](https://mlir.llvm.org/talks/) section.*
+
+
+# Resources
+
+For more information on MLIR, please see:
+- The MLIR section of the LLVM [forums](https://llvm.discourse.group/c/mlir/31) for any questions.
+- Real-time discussion on the MLIR channel of the LLVM [discord](https://discord.gg/xS7Z362) server.
+- Previous [talks](https://mlir.llvm.org/talks/).
+
+# MLIR (Multi-Level Intermediate Representation)
+
+**MLIR is intended to be a hybrid IR which can support multiple different requirements in a unified infrastructure. For example, this includes:**
+- The ability to represent dataflow graphs (such as in TensorFlow), including dynamic shapes, the user-extensible op ecosystem, TensorFlow variables, etc.
+- Optimizations and transformations typically done on such graphs (e.g. in Grappler).
+- Ability to host high-performance-computing-style loop optimizations across kernels (fusion, loop interchange, tiling, etc.), and to transform memory layouts of data.
+- Code generation “lowering” transformations such as DMA insertion, explicit cache management, memory tiling, and vectorization for 1D and 2D register architectures.
+- Ability to represent target-specific operations, e.g. accelerator-specific high-level operations.
+- Quantization and other graph transformations done on a Deep-Learning graph.
+- [Polyhedral](https://mlir.llvm.org/docs/Dialects/Affine/) primitives.
+- [HTS](https://circt.llvm.org/) (Hardware Synthesis Tools)
+
+# FAQ
+ Please visit the [site](https://mlir.llvm.org/getting_started/Faq) to see frequently asked questions.
+
+# Citing
+Please see the [FAQ entry](https://mlir.llvm.org/getting_started/Faq/#how-to-refer-to-mlir-in-publications-is-there-an-accompanying-paper) on how to cite MLIR in publications.
+
+**See [here](https://mlir.llvm.org/) for more information.**
+
 
-See [https://mlir.llvm.org/](https://mlir.llvm.org/) for more information.

mlir/docs/Interfaces.md

 
 A dialect interface can be defined by inheriting from the
 [CRTP](https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern) base
 class `DialectInterfaceBase::Base<>`. This class provides the necessary
 utilities for registering an interface with a dialect so that it can be
 referenced later. Once the interface has been defined, dialects can override it
 using dialect-specific information. The interfaces defined by a dialect are
 registered via `addInterfaces<>`, a similar mechanism to Attributes, Operations,
-Types, etc
+Types, etc.
 
 ```c++
 /// Define a base inlining interface class to allow for dialects to opt-in to
 /// the inliner.
 class DialectInlinerInterface :
     public DialectInterface::Base<DialectInlinerInterface> {
 public:
   /// Returns true if the given region 'src' can be inlined into the region
if (DialectInlinerInterface *interface = dyn_cast<DialectInlinerInterface>(dialect)) {
   // The dialect has provided an implementation of this interface.
   ...
 }
 ```
 
 #### DialectInterfaceCollection
 
 An additional utility is provided via `DialectInterfaceCollection`. This class
-allows for collecting all of the dialects that have registered a given interface
+allows collecting all of the dialects that have registered a given interface
 within an instance of the `MLIRContext`. This can be useful to hide and optimize
 the lookup of a registered dialect interface.
 
 ```c++
 class InlinerInterface : public
     DialectInterfaceCollection<DialectInlinerInterface> {
   /// The hooks for this class mirror the hooks for the DialectInlinerInterface,
   /// with default implementations that call the hook on the interface for a

 The side effects of an operation are generally tied to the semantics of a
 specific operation, for example an `affine.load` operation has a `read` effect
 (as the name may suggest).
 
 These interfaces are defined by overriding the
 [CRTP](https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern) class
 for the specific IR entity; `AttrInterface`, `OpInterface`, or `TypeInterface`
 respectively. These classes take, as a template parameter, a `Traits` class that
 defines a `Concept` and a `Model` class. These classes provide an implementation
 of concept-based polymorphism, where the `Concept` defines a set of virtual
 methods that are overridden by the `Model` that is templated on the concrete
 entity type. It is important to note that these classes should be pure, and
 should not contain non-static data members or other mutable data. To attach an
 interface to an object, the base interface classes provide a
 [`Trait`](Traits.md) class that can be appended to the trait list of that
 object.
 
*   Extra Class Declarations (Optional: `extraClassDeclaration`)
     -   Additional C++ code that is generated in the declaration of the
         interface class. This allows for defining methods and more on the user
         facing interface class, that do not need to hook into the IR entity.
         These declarations are _not_ implicitly visible in default
         implementations of interface methods, but static declarations may be
         accessed with full name qualification.
 *   Extra Shared Class Declarations (Optional: `extraSharedClassDeclaration`)
     -   Additional C++ code that is injected into the declarations of both the
-        interface and trait class. This allows for defining methods and more
-        that are exposed on both the interface and trait class, e.g. to inject
+        interface and the trait class. This allows for defining methods and more
+        that are exposed on both the interface and the trait class, e.g. to inject
         utilties on both the interface and the derived entity implementing the
         interface (e.g. attribute, operation, etc.).
     -   In non-static methods, `$_attr`/`$_op`/`$_type`
         (depending on the type of interface) may be used to refer to an
         instance of the IR entity. In the interface declaration, the type of
         the instance is the interface class. In the trait declaration, the
         type of the instance is the concrete entity class
         (e.g. `IntegerAttr`, `FuncOp`, etc.).
let methods = [
     }],
       "bool", "isSafeToTransform", (ins), /*methodBody=*/[{}],
       /*defaultImplementation=*/[{
     }]>,
   ];
 }
 
 // Operation interfaces can optionally be wrapped inside
-// DeclareOpInterfaceMethods. This would result in autogenerating declarations
+// `DeclareOpInterfaceMethods`. This would result in autogenerating declarations
 // for members `foo`, `bar` and `fooStatic`. Methods with bodies are not
 // declared inside the op declaration but instead handled by the op interface
 // trait directly.
 def OpWithInferTypeInterfaceOp : Op<...
     [DeclareOpInterfaceMethods<MyInterface>]> { ... }
 
 // Methods that have a default implementation do not have declarations
 // generated. If an operation wishes to override the default behavior, it can

mlir/docs/LangRef.md

 
 This document defines and describes the key concepts in MLIR, and is intended to
 be a dry reference document - the
 [rationale documentation](Rationale/Rationale.md),
 [glossary](../getting_started/Glossary.md), and other content are hosted
 elsewhere.
 
 MLIR is designed to be used in three different forms: a human-readable textual
 form suitable for debugging, an in-memory form suitable for programmatic
 transformations and analysis, and a compact serialized form suitable for storage
-and transport. The different forms all describe the same semantic content. This
+and transport. All the different forms describes the same semantic content. This
 document describes the human-readable textual form.
 
 [TOC]
 
 ## High-Level Structure
 
 MLIR is fundamentally based on a graph-like data structure of nodes, called
 *Operations*, and edges, called *Values*. Each Value is the result of exactly
 one Operation or Block Argument, and has a *Value Type* defined by the
 [type system](#type-system). [Operations](#operations) are contained in
 [Blocks](#blocks) and Blocks are contained in [Regions](#regions). Operations
 are also ordered within their containing block and Blocks are ordered in their
 containing region, although this order may or may not be semantically meaningful
 in a given [kind of region](Interfaces.md/#regionkindinterfaces)). Operations
 may also contain regions, enabling hierarchical structures to be represented.
 
 Operations can represent many different concepts, from higher-level concepts
 like function definitions, function calls, buffer allocations, view or slices of
 buffers, and process creation, to lower-level concepts like target-independent
 arithmetic, target-specific instructions, configuration registers, and logic
 gates. These different concepts are represented by different operations in MLIR
 and the set of operations usable in MLIR can be arbitrarily extended.
 
 MLIR also provides an extensible framework for transformations on operations,
 using familiar concepts of compiler [Passes](Passes.md). Enabling an arbitrary
 set of passes on an arbitrary set of operations results in a significant scaling
 challenge, since each transformation must potentially take into account the
 semantics of any operation. MLIR addresses this complexity by allowing operation
 semantics to be described abstractly using [Traits](Traits.md) and
 [Interfaces](Interfaces.md), enabling transformations to operate on operations
 more generically. Traits often describe verification constraints on valid IR,
 enabling complex invariants to be captured and checked. (see

 [SSACFG regions](#control-flow-and-ssacfg-regions), each block represents a
 compiler [basic block](https://en.wikipedia.org/wiki/Basic_block) where
 instructions inside the block are executed in order and terminator operations
 implement control flow branches between basic blocks.
 
 A region with a single block may not include a
 [terminator operation](#terminator-operations). The enclosing op can opt-out of
 this requirement with the `NoTerminator` trait. The top-level `ModuleOp` is an
-example of such operation which defined this trait and whose block body does not
+example of such operation which defines this trait and whose block body does not
 have a terminator.
 
 Blocks in MLIR take a list of block arguments, notated in a function-like way.
 Block arguments are bound to values specified by the semantics of individual
 operations. Block arguments of the entry block of a region are also arguments to
 the region and the values bound to these arguments are determined by the
 semantics of the containing operation. Block arguments of other blocks are
 determined by the semantics of terminator operations, e.g. Branches, which have

 
 -   *inherent attributes* are inherent to the definition of an operation's
     semantics. The operation itself is expected to verify the consistency of
     these attributes. An example is the `predicate` attribute of the
     `arith.cmpi` op. These attributes must have names that do not start with a
     dialect prefix.
 
 -   *discardable attributes* have semantics defined externally to the operation
-    itself, but must be compatible with the operations's semantics. These
+    itself, but must be compatible with the operations' semantics. These
     attributes must have names that start with a dialect prefix. The dialect
     indicated by the dialect prefix is expected to verify these attributes. An
     example is the `gpu.container_module` attribute.
 
 Note that attribute values are allowed to themselves be dictionary attributes,
 but only the top-level dictionary attribute attached to the operation is subject
 to the classification above.
 

 ```
 
 Sufficiently complex dialect attribute values are required to use the verbose
 form for generality. For example, the more complex type shown above would not be
 valid in the lighter syntax: `#foo.something<a%%123^^^>>>` because it contains
 characters that are not allowed in the lighter syntax, as well as unbalanced
 `<>` characters.
 
-See [here](AttributesAndTypes.md) on how to define dialect attribute values.
+See [here](AttributesAndTypes.md) to learn how to define dialect attribute values.
 
 ### Builtin Attribute Values
 
 The [builtin dialect](Dialects/Builtin.md) defines a set of attribute values
 that are directly usable by any other dialect in MLIR. These types cover a range
 from primitive integer and floating-point values, attribute dictionaries, dense
 multi-dimensional arrays, and more.

mlir/docs/OpDefinitions.md

 # Operation Definition Specification (ODS)
 
 In addition to specializing the `mlir::Op` C++ template, MLIR also supports
 defining operations and data types in a table-driven manner. This is achieved
 via [TableGen][TableGen], which is both a generic language and its tooling to
 maintain records of domain-specific information. Facts regarding an operation
 are specified concisely into a TableGen record, which will be expanded into an
 equivalent `mlir::Op` C++ template specialization at compiler build time.
 
 This manual explains in detail all the available mechanisms for defining
 operations in such a table-driven manner. It aims to be a specification instead
 of a tutorial. Please refer to
 [Quickstart tutorial to adding MLIR graph rewrite](Tutorials/QuickstartRewrites.md)
 for the latter.
 
 In addition to detailing each mechanism, this manual also tries to capture best
 practices. They are rendered as quoted bullet points.
 
 ## Motivation
 
 MLIR allows pluggable dialects, and dialects contain, among others, a list of
 operations. This open and extensible ecosystem leads to the "stringly" type IR
 problem, e.g., repetitive string comparisons during optimization and analysis
 passes, unintuitive accessor methods (e.g., generic/error prone `getOperand(3)`
 vs self-documenting `getStride()`) with more generic return types, verbose and
-generic constructors without default arguments, verbose textual IR dump, and so
+generic constructors without default arguments, verbose textual IR dumps, and so
 on. Furthermore, operation verification is:
 
 1.  best case: a central string-to-verification-function map,
 1.  middle case: duplication of verification across the code base, or
 1.  worst case: no verification functions.
 
 The fix is to support defining ops in a table-driven manner. Then for each
 dialect, we can have a central place that contains everything you need to know
*   **Facilitating auto-generation**: The usage of these operation information
     records are by no means limited to op definition itself. We can use them to
     drive the auto-generation of many other components, like computation graph
     serialization.
 
 ## TableGen Syntax
 
 We use TableGen as the language for specifying operation information. TableGen
 itself just provides syntax for writing records; the syntax and constructs
-allowed in a TableGen file (typically with filename suffix `.td`) can be found
+allowed in a TableGen file (typically with the filename suffix `.td`) can be found
 [here][TableGenProgRef].
 
 *   TableGen `class` is similar to C++ class; it can be templated and
     subclassed.
 *   TableGen `def` is similar to C++ object; it can be declared by specializing
     a TableGen `class` (e.g., `def MyDef : MyClass<...>;`) or completely
     independently (e.g., `def MyDef;`). It cannot be further templated or
     subclassed.
 *   TableGen `dag` is a dedicated type for directed acyclic graph of elements. A
     `dag` has one operator and zero or more arguments. Its syntax is `(operator
     arg0, arg1, argN)`. The operator can be any TableGen `def`; an argument can
     be anything, including `dag` itself. We can have names attached to both the
     operator and the arguments like `(MyOp:$op_name MyArg:$arg_name)`.
 
 Please see the [language reference][TableGenProgRef] to learn about all the
 types and expressions supported by TableGen.
 
 ## Operation Definition
 
 MLIR defines several common constructs to help operation definition and provide
 their semantics via a special [TableGen backend][TableGenBackend]:
 [`OpDefinitionsGen`][OpDefinitionsGen]. These constructs are defined in
-[`OpBase.td`][OpBase]. The main ones are
+[`OpBase.td`][OpBase]. The main ones are:
 
 *   The `Op` class: It is the main construct for defining operations. All facts
     regarding the operation are specified when specializing this class, with the
     help of the following constructs.
 *   The `Dialect` class: Operations belonging to one logical group are placed in
     the same dialect. The `Dialect` class contains dialect-level information.
 *   The `OpTrait` class hierarchy: They are used to specify special properties
     and constraints of the operation, including whether the operation has side
     effect or whether its output has the same shape as the input.
 *   The `ins`/`outs` marker: These are two special markers builtin to the
-    `OpDefinitionsGen` backend. They lead the definitions of operands/attributes
+    `OpDefinitionsGen` backend. They lead to the definitions of operands/attributes
     and results respectively.
 *   The `TypeConstraint` class hierarchy: They are used to specify the
     constraints over operands or results. A notable subclass hierarchy is
     `Type`, which stands for constraints for common C++ types.
 *   The `AttrConstraint` class hierarchy: They are used to specify the
     constraints over attributes. A notable subclass hierarchy is `Attr`, which
     stands for constraints for attributes whose values are of common types.
 

 }
 ```
 
 In the following we describe all the fields needed. Please see the definition of
 the `Op` class for the complete list of fields supported.
 
 ### Operation name
 
-The operation name is a unique identifier of the operation within MLIR, e.g.,
+The operation name is a unique identifier for the operation within MLIR, e.g.,
 `tf.Add` for addition operation in the TensorFlow dialect. This is the
 equivalent of the mnemonic in assembly language. It is used for parsing and
 printing in the textual format. It is also used for pattern matching in graph
 rewrites.
 
 The full operation name is composed of the dialect name and the op name, with
 the former provided via the dialect and the latter provided as the second
 template parameter to the `Op` class.

 information.
 
 There is no requirements on the relative order of operands and attributes; they
 can mix freely. The relative order of operands themselves matters. From each
 named argument a named getter will be generated that returns the argument with
 the return type (in the case of attributes the return type will be constructed
 from the storage type, while for operands it will be `Value`). Each attribute's
 raw value (e.g., as stored) can also be accessed via generated `<name>Attr`
-getters for use in transformation passes where the more user friendly return
+getters for use in transformation passes where the more user-friendly return
 type is less suitable.
 
-All the arguments should be named to 1) provide documentation, 2) drive
-auto-generation of getter methods, 3) provide a handle to reference for other
-places like constraints.
+All the arguments should be named to:
+- provide documentation.
+- drive auto-generation of getter methods.
+- provide a handle to reference for other places like constraints.
 
 #### Variadic operands
 
 To declare a variadic operand, wrap the `TypeConstraint` for the operand with
 `Variadic<...>`.
 
 Normally operations have no variadic operands or just one variadic operand. For
 the latter case, it is easy to deduce which dynamic operands are for the static
-variadic operand definition. Though, if an operation has more than one variable
+variadic operand definition. However, if an operation has more than one variable
 length operands (either optional or variadic), it would be impossible to
 attribute dynamic operands to the corresponding static variadic operand
 definitions without further information from the operation. Therefore, either
 the `SameVariadicOperandSize` or `AttrSizedOperandSegments` trait is needed to
 indicate that all variable length operands have the same number of dynamic
 values.
 
 #### VariadicOfVariadic operands

 
 #### Optional operands
 
 To declare an optional operand, wrap the `TypeConstraint` for the operand with
 `Optional<...>`.
 
 Normally operations have no optional operands or just one optional operand. For
 the latter case, it is easy to deduce which dynamic operands are for the static
-operand definition. Though, if an operation has more than one variable length
+operand definition. However, if an operation has more than one variable length
 operands (either optional or variadic), it would be impossible to attribute
 dynamic operands to the corresponding static variadic operand definitions
 without further information from the operation. Therefore, either the
 `SameVariadicOperandSize` or `AttrSizedOperandSegments` trait is needed to
 indicate that all variable length operands have the same number of dynamic
 values.
 
 #### Optional attributes

 
 // (And manually specified builders depending on the specific op.)
 ```
 
 The first form provides basic uniformity so that we can create ops using the
 same form regardless of the exact op. This is particularly useful for
 implementing declarative pattern rewrites.
 
-The second and third forms are good for use in manually written code given that
+The second and third forms are good for use in manually written code, given that
 they provide better guarantee via signatures.
 
 The third form will be generated if any of the op's attribute has different
 `Attr.returnType` from `Attr.storageType` and we know how to build an attribute
 from an unwrapped value (i.e., `Attr.constBuilderCall` is defined.)
 Additionally, for the third form, if an attribute appearing later in the
 `arguments` list has a default value, the default value will be supplied in the
 declaration. This works for `BoolAttr`, `StrAttr`, `EnumAttr` for now and the
-list can grow in the future. So if possible, default valued attribute should be
+list can grow in the future. So if possible, the default valued attribute should be
 placed at the end of the `arguments` list to leverage this feature. (This
 behavior is essentially due to C++ function parameter default value placement
 restrictions.) Otherwise, the builder of the third form will still be generated
 but default values for the attributes not at the end of the `arguments` list
 will not be supplied in the builder's signature.
 
-ODS will generate a builder that doesn't require return type specified if
+ODS will generate a builder that doesn't require the return type specified if
 
 *   Op implements InferTypeOpInterface interface;
 *   All return types are either buildable types or are the same as a given
     operand (e.g., `AllTypesMatch` constraint between operand and result);
 
 And there may potentially exist other builders depending on the specific op;
 please refer to the
 [generated C++ file](#run-mlir-tblgen-to-see-the-generated-content) for the

 any ill-formed operation. Except that, The other verifications can be
 implemented with `hasVerifier`. Check the next section for the execution order
 of these verification methods.
 
 #### Verification Ordering
 
 The verification of an operation involves several steps,
 
 1. StructuralOpTrait will be verified first, they can be run independently.
 1. `verifyInvariants` which is constructed by ODS, it verifies the type,
    attributes, .etc.
 1. Other Traits/Interfaces that have marked their verifier as `verifyTrait` or
    `verifyWithRegions=0`.
-1. Custom verifier which is defined in the op and has marked `hasVerifier=1`
+1. Custom verifier which is defined in the op and has been marked `hasVerifier=1`
 
 If an operation has regions, then it may have the second phase,
 
 1. Traits/Interfaces that have marked their verifier as `verifyRegionTrait` or
    `verifyWithRegions=1`. This implies the verifier needs to access the
    operations in its regions.
-1. Custom verifier which is defined in the op and has marked
+1. Custom verifier which is defined in the op and has been marked
    `hasRegionVerifier=1`
 
 Note that the second phase will be run after the operations in the region are
 verified. Verifiers further down the order can rely on certain invariants being
 verified by a previous verifier and do not need to re-verify them.
 
 #### Emitting diagnostics in custom verifiers
 
 Custom verifiers should avoid printing operations using custom operation

mlir/docs/PDLL.md

 pattern compilation.
 
 ## Rationale
 
 This section provides details on various design decisions, their rationale, and
 alternatives considered when designing PDLL. Given the nature of software
 development, this section may include references to areas of the MLIR compiler
 that no longer exist.
 
 ### Why build a new language instead of improving TableGen DRR?
 
-Note: The section assumes familiarity with
+Note: This section assumes familiarity with
 [TDRR](https://mlir.llvm.org/docs/DeclarativeRewrites/), please refer the
 relevant documentation before continuing.
 
 Tablegen DRR (TDRR), i.e.
 [Table-driven Declarative Rewrite Rules](https://mlir.llvm.org/docs/DeclarativeRewrites/),
 is a declarative DSL for defining MLIR pattern rewrites within the
 [TableGen](https://llvm.org/docs/TableGen/index.html) language. This
 infrastructure is currently the main way in which patterns may be defined

mlir/docs/PassManagement.md

*   Must not inspect the state of sibling operations.
     *   Other threads may be modifying these operations in parallel.
     *   Inspecting the state of ancestor/parent operations is permitted.
 *   Must not maintain mutable pass state across invocations of `runOnOperation`.
     A pass may be run on many different operations with no guarantee of
     execution order.
     *   When multithreading, a specific pass instance may not even execute on
         all operations within the IR. As such, a pass should not rely on running
         on all operations.
 *   Must not maintain any global mutable state, e.g. static variables within the
     source file. All mutable state should be maintained by an instance of the
     pass.
 *   Must be copy-constructible
     *   Multiple instances of the pass may be created by the pass manager to
         process operations in parallel.
 
 When creating an operation pass, there are two different types to choose from
 depending on the usage scenario:

 ```
 
 ### Dependent Dialects
 
 Dialects must be loaded in the MLIRContext before entities from these dialects
 (operations, types, attributes, ...) can be created. Dialects must also be
 loaded before starting the execution of a multi-threaded pass pipeline. To this
 end, a pass that may create an entity from a dialect that isn't guaranteed to
-already ne loaded must express this by overriding the `getDependentDialects()`
+already be loaded must express this by overriding the `getDependentDialects()`
 method and declare this list of Dialects explicitly.
 
 ### Initialization
 
 In certain situations, a Pass may contain state that is constructed dynamically,
 but is potentially expensive to recompute in successive runs of the Pass. One
 such example is when using [`PDL`-based](Dialects/PDLOps.md)
 [patterns](PatternRewriter.md), which are compiled into a bytecode during
*   All Pass classes automatically provide the following utilities for
     *   `markAnalysesPreserved<>`
 
 ```c++
 void MyOperationPass::runOnOperation() {
   // Mark all analyses as preserved. This is useful if a pass can guarantee
   // that no transformation was performed.
   markAllAnalysesPreserved();
 
   // Mark specific analyses as preserved. This is used if some transformation
   // was performed, but some analyses were either unaffected or explicitly
   // preserved.
   markAnalysesPreserved<MyAnalysis, MyAnalyses...>();
 }
 ```
 
 ## Pass Failure
 

 ### Tablegen Specification
 
 The `Pass` class is used to begin a new pass definition. This class takes as an
 argument the registry argument to attribute to the pass, as well as an optional
 string corresponding to the operation type that the pass operates on. The class
 contains the following fields:
 
 *   `summary`
-    -   A short one line summary of the pass, used as the description when
+    -   A short one-line summary of the pass, used as the description when
         registering the pass.
 *   `description`
     -   A longer, more detailed description of the pass. This is used when
         generating pass documentation.
 *   `dependentDialects`
     -   A list of strings representing the `Dialect` classes this pass may
         introduce entities, Attributes/Operations/Types/etc., of.
 *   `constructor`
*   C++ variable name
     -   A name to use for the generated option variable.
 *   argument
     -   The argument name of the option.
 *   type
     -   The C++ type of the option.
 *   default value
     -   The default option value.
 *   description
-    -   A one line description of the option.
+    -   A one-line description of the option.
 *   additional option flags
     -   A string containing any additional options necessary to construct the
         option.
 
 ```tablegen
 def MyPass : Pass<"my-pass"> {
   let options = [
     Option<"option", "example-option", "bool", /*default=*/"true",
            "An example option">,
   ];
 }
 ```
 
 The `ListOption` class takes the following fields:
 
 *   C++ variable name
     -   A name to use for the generated option variable.
 *   argument
     -   The argument name of the option.
 *   element type
     -   The C++ type of the list element.
 *   description
-    -   A one line description of the option.
+    -   A one-line description of the option.
 *   additional option flags
     -   A string containing any additional options necessary to construct the
         option.
 
 ```tablegen
 def MyPass : Pass<"my-pass"> {
   let options = [
     ListOption<"listOption", "example-list", "int64_t",
                "An example list option", "llvm::cl::ZeroOrMore">
   ];
 }
 ```
 
 #### Statistic
 
 Statistics may be specified via the `Statistic`, which takes the following
 template parameters:
 
 *   C++ variable name
     -   A name to use for the generated statistic variable.
 *   display name
     -   The name used when displaying the statistic.
 *   description
-    -   A one line description of the statistic.
+    -   A one-line description of the statistic.
 
 ```tablegen
 def MyPass : Pass<"my-pass"> {
   let statistics = [
     Statistic<"statistic", "example-statistic", "An example statistic">
   ];
 }
 ```
 
 ## Pass Instrumentation
 
 MLIR provides a customizable framework to instrument pass execution and analysis
 computation, via the `PassInstrumentation` class. This class provides hooks into
 the PassManager that observe various events:
 
 *   `runBeforePipeline`
     *   This callback is run just before a pass pipeline, i.e. pass manager, is
         executed.
 *   `runAfterPipeline`
     *   This callback is run right after a pass pipeline has been executed,
         successfully or not.
 *   `runBeforePass`

 *   `runAfterAnalysis`
     *   This callback is run right after an analysis is computed.
 
 PassInstrumentation instances may be registered directly with a
 [PassManager](#pass-manager) instance via the `addInstrumentation` method.
 Instrumentations added to the PassManager are run in a stack like fashion, i.e.
 the last instrumentation to execute a `runBefore*` hook will be the first to
 execute the respective `runAfter*` hook. The hooks of a `PassInstrumentation`
-class are guaranteed to be executed in a thread safe fashion, so additional
+class are guaranteed to be executed in a thread-safe fashion, so additional
 synchronization is not necessary. Below in an example instrumentation that
 counts the number of times the `DominanceInfo` analysis is computed:
 
 ```c++
 struct DominanceCounterInstrumentation : public PassInstrumentation {
   /// The cumulative count of how many times dominance has been calculated.
   unsigned &count;
 

mlir/docs/PatternRewriter.md

 
 The `PatternRewriter` inherits from the `OpBuilder` class, and thus provides all
 of the same functionality present within an `OpBuilder`. This includes operation
 creation, as well as many useful attribute and type construction methods.
 
 ## Pattern Application
 
 After a set of patterns have been defined, they are collected and provided to a
-specific driver for application. A driver consists of several high levels parts:
+specific driver for application. A driver consists of several high level parts:
 
 *   Input `RewritePatternSet`
 
 The input patterns to a driver are provided in the form of an
 `RewritePatternSet`. This class provides a simplified API for building a
 list of patterns.
 
 *   Driver-specific `PatternRewriter`

mlir/docs/README.md

+# MLIR documentation
+
+Please note [this](mlir.llvm.org) is where MLIR's rendered documentation is displayed.
+The viewing experience on GitHub or elsewhere may not match those of the
+website. For any changes please verify instead that they work on the main
+website first.
+
+See [here](https://github.com/llvm/mlir-www) for the website generation information.

mlir/docs/README.txt

-MLIR documentation
-==================
-
-Please note mlir.llvm.org is where MLIR's rendered documentation is displayed.
-The viewing experience on GitHub or elsewhere may not match those of the
-website. For any changes please verify instead that they work on the main
-website first.
-
-See https://github.com/llvm/mlir-www for the website generation information.