[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
----------------
matthias-springer wrote:

Can we add another section for builders? Then you could describe builder API in the builder section and rewriter API in the rewriter section.

There are a few best practices for designing public APIs that we should mention in the introduction of this file (feel free to reformulate):

* Functions that create IR typically take an `OpBuilder &` as the first argument. This indicates to programmers that the function will likely create new IR and allows them to listen to it.
* Functions that modify existing IR (and maybe also build new IR) typically take a `RewriterBase &` as the first argument.
* Prefer `OpBuilder` over `RewriterBase` if possible. The presence of an `OpBuilder &` function argument typically indicates that the function does not modify existing IR. (Unless it is documented.)


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