[Mlir-commits] [mlir] [MLIR] Remark more document (PR #159284)

[Guray Ozen]

https://github.com/grypp created https://github.com/llvm/llvm-project/pull/159284

None

>From e4e2d1f110aa03a4bf53a38e261231bbb446f01c Mon Sep 17 00:00:00 2001
From: Guray Ozen <gozen at nvidia.com>
Date: Wed, 17 Sep 2025 10:45:51 +0200
Subject: [PATCH] [MLIR] Remark more document

---
 mlir/docs/Remarks.md | 69 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 65 insertions(+), 4 deletions(-)

diff --git a/mlir/docs/Remarks.md b/mlir/docs/Remarks.md
index ee2ea855b8a6a..666ee568aec1a 100644
--- a/mlir/docs/Remarks.md
+++ b/mlir/docs/Remarks.md
@@ -94,10 +94,22 @@ Neutral analysis results.
 
 ***
 
+Here’s a cleaned-up and grammatically improved version of your text:
+
+---
+
 ## Emitting Remarks
 
-The `remark::*` helpers return an **in-flight remark**.
-You append strings or key–value metrics using `<<`.
+The `remark::*` helpers return an **`InFlightRemark`**. You can append strings
+or key–value metrics using the `<<` operator.
+
+By default, the remark is emitted as soon as the `InFlightRemark` object is
+destroyed (typically at the end of its scope). However, it can sometimes be
+useful to postpone emitting the remark until the end of the compilation—for example,
+to collect all remarks, sort them, and emit them differently later.
+
+If this behavior is desired, the `RemarkEngine` can be used to store postponed remarks.
+[See this example of postponing remark emission](#example-postpone-remarks-emitting).
 
 ### Remark Options
 
@@ -108,8 +120,9 @@ When constructing a remark, you typically provide four fields that are `StringRe
 3. **Sub-category** – more fine-grained classification
 4. **Function name** – the function where the remark originates
 
+### Examples
 
-### Example
+#### Emitting remarks
 
 ```c++
 #include "mlir/IR/Remarks.h"
@@ -145,6 +158,19 @@ LogicalResult MyPass::runOnOperation() {
 }
 ```
 
+#### Example: Postpone remarks emitting
+
+`RemarkOpts` has `postpone` option. When it is set, the remark emissing will be
+postponed until the end of the compilation.
+
+```c++
+
+  remark::passed(loc, remark::RemarkOpts::name("")
+                            .category(categoryLoopunroll)
+                            .subCategory(myPassname2)
+                            .postpone())
+```
+
 ***
 
 ### Metrics and Shortcuts
@@ -189,7 +215,42 @@ metric("Remark", "vectorized loop")
 
 ***
 
-## Enabling Remarks
+## Enabling Remarks with `mlir-opt`
+
+`mlir-opt` provides flags to enable and configure remarks. The available flags
+are shown below:
+
+```bash
+$> mlir-opt --help
+  ...
+Remark Options:
+Filter remarks by regular expression (llvm::Regex syntax).
+
+  --remark-format=<value>                     - Specify the format for remark output.
+    =emitRemark                               -   Print as emitRemark to the command line
+    =yaml                                     -   Print as a YAML file
+    =bitstream                                -   Print as a bitstream file
+  --remarks-filter=<string>                   - Show all remarks: passed, missed, failed, analysis
+  --remarks-filter-analyse=<string>           - Show analysis remarks
+  --remarks-filter-failed=<string>             - Show failed remarks
+  --remarks-filter-missed=<string>             - Show missed remarks
+  --remarks-filter-passed=<string>             - Show passed remarks
+  --remarks-output-file=<string>               - Output file for YAML and bitstream remark formats (default: mlir-remarks.yaml or mlir-remarks.bitstream)
+```
+
+There are five filter flags to select specific categories. The
+`--remarks-filter` flag is a general shortcut that applies to all remark
+categories. Their usage is as follows:
+
+```bash
+# This will only match remarks in the "my-interesting-category" category
+mlir-opt --remarks-filter="my-interesting-category"
+
+# You can also use "*" to match categories starting with "my"
+mlir-opt --remarks-filter="my*"
+```
+
+## Enabling Remarks for downstream compilers via APIs
 
 ### 1. **With LLVMRemarkStreamer (YAML or Bitstream)**