[mlir][docs] Guide on generating alias for type/attribute

mlir/docs/DefiningDialects/Assembly.md

@@ -0,0 +1,51 @@
+# Customizing Assembly Behavior
+
+[TOC]
+
+## Generating Aliases
+
+To reduce verbosity in the resulting assembly, `AsmPrinter` can generate aliases for frequently used types and attributes.
+
+For example, `!my_dialect.type<a=3,b=4,c=5,d=tuple,e=another_type>` and `#my_dialect.attr<a=3>` can be aliased to `!my_dialect_type` and `#my_dialect_attr`, simplifying further references.
+
+To enable this, the owning dialect of these types/attributes can define an interface to hook into the `AsmPrinter`. This is effective only when the assembly is not printed in generic form.
+
+```cpp
+// OpAsmDialectInterface is defined in
+// https://github.com/llvm/llvm-project/blob/91ab10e8d6c256d841da1a1a1b47c334e08d95b9/mlir/include/mlir/IR/OpImplementation.h#L1738
+struct MyDialectOpAsmDialectInterface : public OpAsmDialectInterface {
+ public:
+  using OpAsmDialectInterface::OpAsmDialectInterface;
+
+  AliasResult getAlias(Type type, raw_ostream& os) const override {
+    if (mlir::isa<MyType>(type)) {
+      os << "my_dialect_type";
+      // Could return OverridableAlias when
+      // allowing other dialect to override the alias.
+      //
+      // Other dialects are allowed to provide alias for
+      // type/attribute not owned by them
+      // but the final result would depend on the registration order
+      // of these dialects in the MLIRContext
+      return AliasResult::FinalAlias;
+    }
+    return AliasResult::NoAlias;
+  }
+
+  AliasResult getAlias(Attribute attr, raw_ostream& os) const override {
+    if (mlir::isa<MyAttribute>(attr)) {
+      os << "my_dialect_attr";
+      return AliasResult::FinalAlias;
+    }
+    return AliasResult::NoAlias;
+  }
+};
+
+void MyDialect::initialize() {
+  // register the interface to the dialect
+  addInterface<MyDialectOpAsmDialectInterface>();
+}
+```
+
+* If `getAlias` provides an alias with a trailing digit, `AsmPrinter` appends an underscore to avoid conflicts with autogenerated IDs.
+* If multiple types/attributes have the same alias from `getAlias`, a number is appended to the alias to avoid conflicts.