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

[Mehdi Amini]

================
@@ -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 `<<`               |
 
-***
+---
----------------
joker-eph wrote:

What are these separators intended to convey?

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