[Mlir-commits] [mlir] MLIR Rewriters: add new listener to emit match failures to user, enhance docs (PR #94130)

[Matthias Springer]

================
@@ -0,0 +1,129 @@
+# Rewriting MLIR
+
+[TOC]
+
+This document details the design and API of the general IR rewriting 
+infrastructure present in MLIR. There are specific implemenations
+of this infrastructure, for example [Pattern Rewriting](PatternRewriter.md),
+which is widely used throughout MLIR for canonicalization, conversion, and
+general transformation.
+
+## Rewriters
+
+### `RewriterBase`
+
+All rewriters extend from [`RewriterBase`](https://mlir.llvm.org/doxygen/classmlir_1_1RewriterBase.html), which inherits from [`OpBuilder`](https://mlir.llvm.org/doxygen/classmlir_1_1OpBuilder.html).
+`RewriterBase` provides common API functions for any general types of rewriting
+IR. It additionally provides a [`Listener`](#listeners) mechanism to keep track of IR
+modifications.
+
+#### Rewriter Implementations
+
+Currently, there are only two implementations of `RewriterBase`:
----------------
matthias-springer wrote:

I'd reformulate that a bit: I'd just say that patterns provide a `PatternRewriter &` in `matchAndRewrite`, and `IRRewriter` allows programmers to use the rewriter API outside of patterns. Helper functions should use `RewriterBase &`, so that they can be called standalone and from within patterns.


https://github.com/llvm/llvm-project/pull/94130