[Mlir-commits] [mlir] [mlir][docs] Document custom op parser and printer methods (PR #195579)

[llvmlistbot at llvm.org]

llvmorg-github-actions[bot] wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-mlir

Author: ashlog

<details>
<summary>Changes</summary>

## Summary
- expand the ODS custom parser/printer documentation for operations
- document the modern `hasCustomAssemblyFormat` path and generated method signatures
- note that old op-level `let parser` / `let printer` hooks are no longer used for operations

Fixes #<!-- -->54442

## Testing
- `git -c core.fsmonitor=false diff --check origin/main..HEAD`

Docs-only change; no LLVM build was run.

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


1 Files Affected:

- (modified) mlir/docs/DefiningDialects/Operations.md (+48-1) 


``````````diff
diff --git a/mlir/docs/DefiningDialects/Operations.md b/mlir/docs/DefiningDialects/Operations.md
index b64bffdf72ae3..48ed793ab73b0 100644
--- a/mlir/docs/DefiningDialects/Operations.md
+++ b/mlir/docs/DefiningDialects/Operations.md
@@ -663,7 +663,54 @@ MyOp::build(::mlir::OpBuilder &builder, ::mlir::OperationState &state,
 
 ### Custom parser and printer methods
 
-Functions to parse and print the operation's custom assembly form.
+Most operations should define their custom assembly form declaratively with
+[`assemblyFormat`](#declarative-assembly-format). If an operation needs parsing
+or printing logic that cannot be expressed with the declarative format, set
+`hasCustomAssemblyFormat` to `1`.
+
+```tablegen
+def MyOp : Op<"my_op", []> {
+  let arguments = (ins AnyType:$input);
+  let results = (outs AnyType:$output);
+
+  let hasCustomAssemblyFormat = 1;
+}
+```
+
+This generates declarations for custom parser and printer methods on the op
+class:
+
+```c++
+static ::mlir::ParseResult parse(::mlir::OpAsmParser &parser,
+                                 ::mlir::OperationState &result);
+void print(::mlir::OpAsmPrinter &printer);
+```
+
+The parser consumes the operation's custom assembly form and populates the
+provided `OperationState` with operands, result types, attributes, properties,
+regions, and successors as needed. The printer emits the same custom form from
+the operation instance.
+
+The implementations are defined in C++:
+
+```c++
+ParseResult MyOp::parse(OpAsmParser &parser, OperationState &result) {
+  // Parse the custom syntax and populate `result`.
+  return success();
+}
+
+void MyOp::print(OpAsmPrinter &printer) {
+  // Print the custom syntax for this operation.
+}
+```
+
+If `assemblyFormat` is specified, it takes precedence over
+`hasCustomAssemblyFormat`. Older operation definitions may refer to inline
+`let parser` or `let printer` hooks; those hooks are no longer used for
+operations. Shared helper logic can still be factored into ordinary C++
+functions, or into declarations/definitions provided with
+[`extraClassDeclaration`](#extra-declarations) and
+[`extraClassDefinition`](#extra-definitions).
 
 ### Custom verifier code
 

``````````

</details>


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