[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
----------------
razvanlupusoru wrote:

> in real-time

Being in real-time depends on the emitting policy

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