[Mlir-commits] [mlir] [MLIR][Remarks] Improve the doc (PR #171128)

[Razvan Lupusoru]

================
@@ -1,259 +1,303 @@
 # Remark Infrastructure
 
 Remarks are **structured, human- and machine-readable notes** emitted by the
-compiler to explain:
+compiler to communicate:
 
-- What was transformed
-- What was missed
-- Why it happened
+- What transformations were applied
+- What optimizations were missed
+- Why certain decisions were made
 
-The **`RemarkEngine`** collects finalized remarks during compilation and sends
-them to a pluggable **streamer**. By default, MLIR integrates with LLVM’s
-[`llvm::remarks`](https://llvm.org/docs/Remarks.html), allowing you to:
+The **`RemarkEngine`** collects remarks during compilation and routes them to a
+pluggable **streamer**. By default, MLIR integrates with LLVM's
+[`llvm::remarks`](https://llvm.org/docs/Remarks.html) infrastructure, enabling
+you to:
 
-- Stream remarks as passes run
-- Serialize them to **YAML** or **LLVM bitstream** for tooling
+- Stream remarks in real-time as passes execute
+- Serialize to **YAML** (human-readable) or **LLVM Bitstream** (compact binary)
 
-***
+---
 
-## Key Points
+## Overview
 
-- **Opt-in** – Disabled by default; zero overhead unless enabled.
-- **Per-context** – Configured on `MLIRContext`.
-- **Formats** – LLVM Remark engine (YAML / Bitstream) or custom streamers.
-- **Kinds** – `Passed`, `Missed`, `Failure`, `Analysis`.
-- **API** – Lightweight streaming interface using `<<` (like MLIR diagnostics).
+| Feature       | Description                                              |
+|---------------|----------------------------------------------------------|
+| **Opt-in**    | Disabled by default; zero overhead when not enabled      |
+| **Per-context** | Configured on `MLIRContext`                            |
+| **Formats**   | YAML, Bitstream, or custom streamers                     |
+| **Kinds**     | `Passed`, `Missed`, `Failure`, `Analysis`                |
+| **API**       | Lightweight streaming interface using `<<`               |
 
-***
+---
 
-## How It Works
+## Architecture
 
-Two main components:
+The remark system consists of two main components:
 
-- **`RemarkEngine`** (owned by `MLIRContext`): Receives finalized
-  `InFlightRemark`s, optionally mirrors them to the `DiagnosticEngine`, and
-  dispatches to the installed streamer.
+### RemarkEngine
 
-- **`MLIRRemarkStreamerBase`** (abstract): Backend interface with a single hook:
+Owned by `MLIRContext`, the engine:
 
-  ```c++
-  virtual void streamOptimizationRemark(const Remark &remark) = 0;
-  ```
+- Receives finalized `InFlightRemark` objects
+- Optionally mirrors remarks to the `DiagnosticEngine`
+- Dispatches to the installed streamer
 
-**Default backend – `MLIRLLVMRemarkStreamer`** Adapts `mlir::Remark` to LLVM’s
-remark format and writes YAML/bitstream via `llvm::remarks::RemarkStreamer`.
+### MLIRRemarkStreamerBase
 
-**Ownership flow:** `MLIRContext` → `RemarkEngine` → `MLIRRemarkStreamerBase`
+An abstract backend interface with a single hook:
 
-***
+```c++
+virtual void streamOptimizationRemark(const Remark &remark) = 0;
+```
+
+The default implementation, **`MLIRLLVMRemarkStreamer`**, adapts `mlir::Remark`
+to LLVM's remark format and writes YAML or Bitstream via
+`llvm::remarks::RemarkStreamer`.
+
+**Ownership chain:** `MLIRContext` → `RemarkEngine` → `MLIRRemarkStreamerBase`
 
-## Categories
+---
 
-MLIR provides four built-in remark categories (extendable if needed):
+## Remark Categories
 
-#### 1. **Passed**
+MLIR provides four built-in categories:
 
-Optimization/transformation succeeded.
+### Passed
+
+An optimization or transformation succeeded.
 
 ```
 [Passed] RemarkName | Category:Vectorizer:myPass1 | Function=foo | Remark="vectorized loop", tripCount=128
 ```
 
-#### 2. **Missed**
+### Missed
 
-Optimization/transformation didn’t apply — ideally with actionable feedback.
+An optimization didn't apply—ideally with actionable feedback.
----------------
razvanlupusoru wrote:

Spaces between the em-dash.

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