[mlir][doc] Fix reported Builtin (syntax) issues (#74635)

Fixes https://github.com/llvm/llvm-project/issues/62489.

Some notes for each number:

- 1 `bool-literal` should be reasonably clear from context.
- 2 Fixed.
- 3 This is now fixed. `loc(fused[])` is valid, but `loc(fused["foo",])`
is not.
- 4 This operation uses `assemblyFormat` so the syntax is correct
(assuming ODS is correct).
- 5 This operation uses `assemblyFormat` so the syntax is correct
(assuming ODS is correct).
- 6 Added an example.
- 7 The suggested fix is in line with other `assemblyFormat` examples.
- 8 Added syntax and an example.
- 9 I don't know what this is referring too.
- 10 Added example.
- 11 and 12 suggestion seems wrong as the `ShapedTypeInterface` could be
extended by clients, so is not limited to tensors or vectors.
- 13 is already reasonably clear with the example, I think.
- 14 is already reasonably clear with the example, I think.
- 15 Added an example from the `opaque_locations.mlir` tests.
- 16 The answer to this seems to change over time and depend on the use
case? Suggestions by reviewers are welcome.

3 files changed, 53 insertions, 15 deletions

diff --git a/mlir/include/mlir/IR/BuiltinAttributes.td b/mlir/include/mlir/IR/BuiltinAttributes.td
index be9cbec..d929593 100644
--- a/mlir/include/mlir/IR/BuiltinAttributes.td
+++ b/mlir/include/mlir/IR/BuiltinAttributes.td
@@ -454,9 +454,15 @@ def Builtin_DenseResourceElementsAttr : Builtin_Attr<"DenseResourceElements",
     Examples:
 
     ```mlir
-    // A tensor referencing a builtin dialect resource, `resource_1`, with two
-    // unsigned i32 elements.
-    dense_resource<resource_1> : tensor<2xui32>
+    "example.user_op"() {attr = dense_resource<blob1> : tensor<3xi64> } : () -> ()
+
+    {-#
+    dialect_resources: {
+        builtin: {
+          blob1: "0x08000000010000000000000002000000000000000300000000000000"
+        }
+      }
+    #-}
     ```
   }];
   let parameters = (ins
diff --git a/mlir/include/mlir/IR/BuiltinLocationAttributes.td b/mlir/include/mlir/IR/BuiltinLocationAttributes.td
index e1656f26..dfcc180 100644
--- a/mlir/include/mlir/IR/BuiltinLocationAttributes.td
+++ b/mlir/include/mlir/IR/BuiltinLocationAttributes.td
@@ -112,8 +112,8 @@ def FusedLoc : Builtin_LocationAttr<"FusedLoc"> {
     Syntax:
 
     ```
-    fused-location ::= `fused` fusion-metadata? `[` location (location `,`)* `]`
     fusion-metadata ::= `<` attribute-value `>`
+    fused-location ::= `fused` fusion-metadata? `[` (location (`,` location)* )? `]`
     ```
 
     An instance of a `fused` location represents a grouping of several other
@@ -126,7 +126,7 @@ def FusedLoc : Builtin_LocationAttr<"FusedLoc"> {
     Example:
 
     ```mlir
-    loc(fused["mysource.cc":10:8, "mysource.cc":22:8)
+    loc(fused["mysource.cc":10:8, "mysource.cc":22:8])
     loc(fused<"CSE">["mysource.cc":10:8, "mysource.cc":22:8])
     ```
   }];
@@ -159,7 +159,7 @@ def NameLoc : Builtin_LocationAttr<"NameLoc"> {
     This can be useful for representing the locations of variable, or node,
     definitions.
 
-    Example:
+    #### Example:
 
     ```mlir
     loc("CSE"("mysource.cc":10:8))
@@ -191,6 +191,13 @@ def OpaqueLoc : Builtin_LocationAttr<"OpaqueLoc"> {
     structure that is external to MLIR and an optional location that can be used
     if the first one is not suitable. Since it contains an external structure,
     only the optional location is used during serialization.
+
+    #### Example:
+
+    ```mlir
+    %0 = "example.operation"() : () -> i32 loc("mysource")
+    %1 = arith.constant 4 : index loc(callsite("mysum" at "mysource.cc":10:8))
+    ```
   }];
   let parameters = (ins "uintptr_t":$underlyingLocation,
                         "TypeID":$underlyingTypeID,
diff --git a/mlir/include/mlir/IR/BuiltinTypes.td b/mlir/include/mlir/IR/BuiltinTypes.td
index 1d77728..4cade83 100644
--- a/mlir/include/mlir/IR/BuiltinTypes.td
+++ b/mlir/include/mlir/IR/BuiltinTypes.td
@@ -47,7 +47,7 @@ def Builtin_Complex : Builtin_Type<"Complex", "complex"> {
     element type, which is composed of a real and imaginary value of that
     element type. The element must be a floating point or integer scalar type.
 
-    Examples:
+    #### Example:
 
     ```mlir
     complex<f32>
@@ -251,6 +251,16 @@ def Builtin_Function : Builtin_Type<"Function", "function"> {
 
     The function type can be thought of as a function signature. It consists of
     a list of formal parameter types and a list of formal result types.
+
+    #### Example:
+
+    ```mlir
+    func.func @add_one(%arg0 : i64) -> i64 {
+      %c1 = arith.constant 1 : i64
+      %0 = arith.addi %arg0, %c1 : i64
+      return %0 : i64
+    }
+    ```
   }];
   let parameters = (ins "ArrayRef<Type>":$inputs, "ArrayRef<Type>":$results);
   let builders = [
@@ -392,10 +402,10 @@ def Builtin_MemRef : Builtin_Type<"MemRef", "memref", [
     Syntax:
 
     ```
-    memref-type ::= `memref` `<` dimension-list-ranked type
-                    (`,` layout-specification)? (`,` memory-space)? `>`
     layout-specification ::= attribute-value
     memory-space ::= attribute-value
+    memref-type ::= `memref` `<` dimension-list-ranked type
+                    (`,` layout-specification)? (`,` memory-space)? `>`
     ```
 
     A `memref` type is a reference to a region of memory (similar to a buffer
@@ -667,8 +677,23 @@ def Builtin_MemRef : Builtin_Type<"MemRef", "memref", [
 def Builtin_None : Builtin_Type<"None", "none"> {
   let summary = "A unit type";
   let description = [{
+    Syntax:
+
+    ```
+    none-type ::= `none`
+    ```
+
     NoneType is a unit type, i.e. a type with exactly one possible value, where
     its value does not have a defined dynamic representation.
+
+    #### Example:
+
+    ```mlir
+    func.func @none_type() {
+      %none_val = "foo.unknown_op"() : () -> none
+      return
+    }
+    ```
   }];
   let extraClassDeclaration = [{
     static NoneType get(MLIRContext *context);
@@ -692,7 +717,7 @@ def Builtin_Opaque : Builtin_Type<"Opaque", "opaque"> {
     represented in their raw string form, and can only usefully be tested for
     type equality.
 
-    Examples:
+    #### Example:
 
     ```mlir
     opaque<"llvm", "struct<(i32, float)>">
@@ -761,7 +786,7 @@ def Builtin_RankedTensor : Builtin_Type<"RankedTensor", "tensor", [
     zero sizes are not allowed in some other types, such tensors should be
     optimized away before lowering tensors to vectors.
 
-    Examples:
+    #### Example:
 
     ```mlir
     // Known rank but unknown dimensions.
@@ -846,7 +871,7 @@ def Builtin_Tuple : Builtin_Type<"Tuple", "tuple"> {
     provides no standard operations for operating on `tuple` types
     ([rationale](../../Rationale/Rationale/#tuple-types)).
 
-    Examples:
+    #### Example:
 
     ```mlir
     // Empty tuple.
@@ -917,7 +942,7 @@ def Builtin_UnrankedMemRef : Builtin_Type<"UnrankedMemRef", "unranked_memref", [
     See [MemRefType](#memreftype) for more information on
     memref types.
 
-    Examples:
+    #### Examples:
 
     ```mlir
     memref<*f32>
@@ -990,7 +1015,7 @@ def Builtin_UnrankedTensor : Builtin_Type<"UnrankedTensor", "unranked_tensor", [
     unknown rank. See [RankedTensorType](#rankedtensortype)
     for more information on tensor types.
 
-    Examples:
+    #### Examples:
 
     ```mlir
     tensor<*xf32>
@@ -1051,7 +1076,7 @@ def Builtin_Vector : Builtin_Type<"Vector", "vector", [ShapedTypeInterface], "Ty
     declarations, `vector<0x42xi32>` is invalid because it is interpreted as a
     2D vector with shape `(0, 42)` and zero shapes are not allowed.
 
-    Examples:
+    #### Examples:
 
     ```mlir
     // A 2D fixed-length vector of 3x42 i32 elements.