[MLIR] Improve Remark documentation to include mlir-opt usage

[grypp]

No description provided.

[llvmbot]

@llvm/pr-subscribers-mlir

Author: Guray Ozen (grypp)

Changes

---

Full diff: https://github.com/llvm/llvm-project/pull/159284.diff

1 Files Affected:

• (modified) mlir/docs/Remarks.md (+65-4)

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)**
 

[Copilot]

Pull Request Overview

This PR enhances the MLIR Remarks documentation by expanding explanations of remark functionality and providing more detailed usage examples. The changes improve clarity around remark emission timing and add comprehensive documentation for command-line options.

• Adds clarification about InFlightRemark behavior and postponed emission
• Introduces a new example demonstrating postponed remark emission using RemarkOpts
• Expands the "Enabling Remarks" section to include detailed mlir-opt command-line flags and usage examples

[joker-eph]

We should document when/why this is useful, not just "what". It's not obvious to me why a remark author would want to use this and when?

[grypp]

I wrote it here:
https://github.com/grypp/llvm-project/blob/cc673be6642b49c2396e07b86c4e4e52c6b0e7a4/mlir/docs/Remarks.md?plain=1#L102-L105

[grypp]

Postponing will be more useful with my new PR.

The new PR allows dropping or replacing earlier remarks when using postponing.
Here’s an example:

pass-early : remark(failed to unroll the loop)
pass-later : drop early remark, add remark(loop is unrolled)

[joker-eph]

It's still not clear to me how this is a decision of the remark author, and the implicit coupling that can exist between the remark and the consumer here?

[joker-eph]

There is still the same issue with the help messages: "Show xxxx" is not well descriptive for something that is a filter.

[joker-eph]

(let's iterate on the postponing thing)