[mlir][SPIRV] Update dialect/op documentation to be consistent with the rest of the dialects

[rriddle]

Summary

This revision performs a lot of different cleanups on operation documentation to ensure that they are consistent:

• using mlir code blocks
• formatting
• removing custom syntax for operations that have it auto-generated

[mravishankar]

A lot of this is auto-generated using https://github.com/llvm/llvm-project/blob/master/mlir/utils/spirv/gen_spirv_dialect.py . Would be better to update that so that it doesnt get reverted when we use the script to regenerate the .td files. Let me know if you want one of us to take that up (should be a simple change.

[rriddle]

In D76735#1942386, @mravishankar wrote:

A lot of this is auto-generated using https://github.com/llvm/llvm-project/blob/master/mlir/utils/spirv/gen_spirv_dialect.py . Would be better to update that so that it doesnt get reverted when we use the script to regenerate the .td files. Let me know if you want one of us to take that up (should be a simple change.

Yes that would be great. Is that going to subsume all of the changes here in the .td files? Note, the .md changes are still necessary regardless.

[mravishankar]

Actually, strike what I said earlier. The script uses the existing text for an op.

But can you just update these two lines of the script to match what you have here. https://github.com/llvm/llvm-project/blob/92744f624783d92a07db25bc76e181b879f17e5b/mlir/utils/spirv/gen_spirv_dialect.py#L677 - #L678

Also I think (@antiagainst can confirm), the ### Custom assembly format is used as a demarcartor by the generator script. I tried to find cases above where it is removed.

mlir/include/mlir/Dialect/SPIRV/SPIRVLogicalOps.td

825

Please dont remove this. It is used by the dialect generator script as a demarcator

mlir/include/mlir/Dialect/SPIRV/SPIRVNonUniformOps.td

70

Please dont remove this. It is used by the dialect generator script as a demarcator

119

Please dont remove this. It is used by the dialect generator script as a demarcator

mlir/include/mlir/Dialect/SPIRV/SPIRVOps.td

137

Please dont remove this. It is used by the dialect generator script as a demarcator

299

Please dont remove this. It is used by the dialect generator script as a demarcator

394

Please dont remove this. It is used by the dialect generator script as a demarcator

mlir/include/mlir/Dialect/SPIRV/SPIRVStructureOps.td

36

Please dont remove this. It is used by the dialect generator script as a demarcator

480

Please dont remove this. It is used by the dialect generator script as a demarcator

[antiagainst]

The first part of description (before ### Custom assembly form) is automatically populated from the SPIR-V spec by the gen_spirv_dialect.py tool. The part after ### Custom assembly form is manually added. So ### Custom assembly form is the anchor at the moment to split. To remove it means we need rethink how the documentation is done. (The Example ... mlir part is fine as Mahesh pointed out.) Can I ask what do we want to achieve here? Will you automatically generate the custom assembly form's doc some way?

[rriddle]

In D76735#1944631, @antiagainst wrote:

The first part of description (before ### Custom assembly form) is automatically populated from the SPIR-V spec by the gen_spirv_dialect.py tool. The part after ### Custom assembly form is manually added. So ### Custom assembly form is the anchor at the moment to split. To remove it means we need rethink how the documentation is done. (The Example ... mlir part is fine as Mahesh pointed out.) Can I ask what do we want to achieve here? Will you automatically generate the custom assembly form's doc some way?

The overall goal is to bring some uniformity to the dialect documentation, and clean it up. The assembly form weirdness comes from the fact that we already generate a section for the syntax when the operation uses the assemblyFormat field, which leads to some redundancy: e.g. https://mlir.llvm.org/docs/Dialects/SPIRVDialect/#spv_address_of-spirvaddressofop

[antiagainst]

In D76735#1944785, @rriddle wrote:

In D76735#1944631, @antiagainst wrote:

The first part of description (before ### Custom assembly form) is automatically populated from the SPIR-V spec by the gen_spirv_dialect.py tool. The part after ### Custom assembly form is manually added. So ### Custom assembly form is the anchor at the moment to split. To remove it means we need rethink how the documentation is done. (The Example ... mlir part is fine as Mahesh pointed out.) Can I ask what do we want to achieve here? Will you automatically generate the custom assembly form's doc some way?

The overall goal is to bring some uniformity to the dialect documentation, and clean it up. The assembly form weirdness comes from the fact that we already generate a section for the syntax when the operation uses the assemblyFormat field, which leads to some redundancy: e.g. https://mlir.llvm.org/docs/Dialects/SPIRVDialect/#spv_address_of-spirvaddressofop

Great. I see now. Let me take over and fix the script to use a different anchor. Thanks River!

mlir/docs/Dialects/SPIR-V.md

-# SPIR-V Dialect
+# `spv` Dialect
 
 This document describes the design of the SPIR-V dialect in MLIR. It lists
 various design choices we made for modeling different SPIR-V mechanisms, and
 their rationale.
 
 This document also explains in a high-level manner how different components are
 organized and implemented in the code and gives steps to follow for extending
 them.

 
 ```mlir
 %0 = "spv.constant"() { value = 42 : i32 } : () -> i32
 %1 = "spv.Variable"(%0) { storage_class = "Function" } : (i32) -> !spv.ptr<i32, Function>
 %2 = "spv.IAdd"(%0, %0) : (i32, i32) -> i32
 ```
 
 Operation documentation is written in each op's Op Definition Spec using
-TableGen. A markdown version of the doc can be found at
-[mlir.llvm.org][LlvmMlirSpirvDoc] or generated using `mlir-tblgen -gen-doc`.
+TableGen. A markdown version of the doc can be generated using `mlir-tblgen
+-gen-doc`.
+
+[include "Dialects/SPIRVOps.md"]
 
 ### Ops from extended instruction sets
 
 Analogically extended instruction set is a mechanism to import SPIR-V
 instructions within another namespace. [`GLSL.std.450`][GlslStd450] is an
 extended instruction set that provides common mathematical routines that should
 be supported. Instead of modeling `OpExtInstImport` as a separate op and use a
 single op to model `OpExtInst` for all extended instructions, we model each

 [MlirSpirvBase]: https://github.com/llvm/llvm-project/blob/master/mlir/include/mlir/Dialect/SPIRV/SPIRVBase.td
 [MlirSpirvPasses]: https://github.com/llvm/llvm-project/blob/master/mlir/include/mlir/Dialect/SPIRV/Passes.h
 [MlirSpirvLowering]: https://github.com/llvm/llvm-project/blob/master/mlir/include/mlir/Dialect/SPIRV/SPIRVLowering.h
 [MlirSpirvAbi]: https://github.com/llvm/llvm-project/blob/master/mlir/include/mlir/Dialect/SPIRV/SPIRVLowering.td
 [MlirSpirvOpsCpp]: https://github.com/llvm/llvm-project/blob/master/mlir/lib/Dialect/SPIRV/SPIRVOps.cpp
 [GitHubDialectTracking]: https://github.com/tensorflow/mlir/issues/302
 [GitHubLoweringTracking]: https://github.com/tensorflow/mlir/issues/303
 [GenSpirvUtilsPy]: https://github.com/llvm/llvm-project/blob/master/mlir/utils/spirv/gen_spirv_dialect.py
-[LlvmMlirSpirvDoc]: ../Dialects/SPIRVOps/
 [CustomTypeAttrTutorial]: ../DefiningAttributesAndTypes/
 [VulkanSpirv]: https://renderdoc.org/vkspec_chunked/chap40.html#spirvenv
 [VulkanShaderInterface]: https://renderdoc.org/vkspec_chunked/chap14.html#interfaces-resources
 [VulkanResourceLimits]: https://renderdoc.org/vkspec_chunked/chap36.html#limits

mlir/include/mlir/Dialect/SPIRV/CMakeLists.txt

 add_mlir_dialect(SPIRVOps spv)
-add_mlir_doc(SPIRVOps -gen-dialect-doc SPIRVDialect Dialects/)
+add_mlir_doc(SPIRVOps -gen-op-doc SPIRVOps Dialects/)
 
 set(LLVM_TARGET_DEFINITIONS SPIRVBase.td)
 mlir_tablegen(SPIRVEnums.h.inc -gen-enum-decls)
 mlir_tablegen(SPIRVEnums.cpp.inc -gen-enum-defs)
 add_public_tablegen_target(MLIRSPIRVEnumsIncGen)
 
 set(LLVM_TARGET_DEFINITIONS SPIRVBase.td)
 mlir_tablegen(SPIRVEnumAvailability.h.inc -gen-spirv-enum-avail-decls)

mlir/include/mlir/Dialect/SPIRV/SPIRVArithmeticOps.td

 // -----
 
 def SPV_FAddOp : SPV_ArithmeticBinaryOp<"FAdd", SPV_Float, [Commutative]> {
   let summary = "Floating-point addition of Operand 1 and Operand 2.";
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
-     The types of Operand 1 and Operand 2 both must be the same as Result
-    Type.
+    The types of Operand 1 and Operand 2 both must be the same as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fadd-op ::= ssa-id `=` `spv.FAdd` ssa-use, ssa-use
                           `:` float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.FAdd %0, %1 : f32
     %5 = spv.FAdd %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FDivOp : SPV_ArithmeticBinaryOp<"FDiv", SPV_Float, []> {
   let summary = "Floating-point division of Operand 1 divided by Operand 2.";
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
-     The types of Operand 1 and Operand 2 both must be the same as Result
-    Type.
+    The types of Operand 1 and Operand 2 both must be the same as Result Type.
 
-     Results are computed per component.  The resulting value is undefined
-    if Operand 2 is 0.
+    Results are computed per component.  The resulting value is undefined if
+    Operand 2 is 0.
 
     ### Custom assembly form
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fdiv-op ::= ssa-id `=` `spv.FDiv` ssa-use, ssa-use
                           `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FDiv %0, %1 : f32
     %5 = spv.FDiv %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FModOp : SPV_ArithmeticBinaryOp<"FMod", SPV_Float, []> {
   let summary = [{
     The floating-point remainder whose sign matches the sign of Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
-     The types of Operand 1 and Operand 2 both must be the same as Result
-    Type.
+    The types of Operand 1 and Operand 2 both must be the same as Result Type.
 
-     Results are computed per component.  The resulting value is undefined
     if Operand 2 is 0.  Otherwise, the result is the remainder r of Operand
     1 divided by Operand 2 where if r ≠ 0, the sign of r is the same as the
     sign of Operand 2.
 
     ### Custom assembly form
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fmod-op ::= ssa-id `=` `spv.FMod` ssa-use, ssa-use
                           `:` float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.FMod %0, %1 : f32
     %5 = spv.FMod %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FMulOp : SPV_ArithmeticBinaryOp<"FMul", SPV_Float, [Commutative]> {
   let summary = "Floating-point multiplication of Operand 1 and Operand 2.";
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
-     The types of Operand 1 and Operand 2 both must be the same as Result
-    Type.
+    The types of Operand 1 and Operand 2 both must be the same as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fmul-op ::= `spv.FMul` ssa-use, ssa-use
                           `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FMul %0, %1 : f32
     %5 = spv.FMul %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FNegateOp : SPV_ArithmeticUnaryOp<"FNegate", SPV_Float, []> {
   let summary = "Floating-point subtract of Operand from zero.";
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
-     The type of Operand must be the same as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fmul-op ::= `spv.FNegate` ssa-use `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.FNegate %0 : f32
     %3 = spv.FNegate %2 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FRemOp : SPV_ArithmeticBinaryOp<"FRem", SPV_Float, []> {
   let summary = [{
     The floating-point remainder whose sign matches the sign of Operand 1.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
-     The types of Operand 1 and Operand 2 both must be the same as Result
     Type.
 
-     Results are computed per component.  The resulting value is undefined
     if Operand 2 is 0.  Otherwise, the result is the remainder r of Operand
     1 divided by Operand 2 where if r ≠ 0, the sign of r is the same as the
     sign of Operand 1.
 
     ### Custom assembly form
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     frem-op ::= ssa-id `=` `spv.FRemOp` ssa-use, ssa-use
                           `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FRemOp %0, %1 : f32
     %5 = spv.FRemOp %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FSubOp : SPV_ArithmeticBinaryOp<"FSub", SPV_Float, []> {
   let summary = "Floating-point subtraction of Operand 2 from Operand 1.";
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
-     The types of Operand 1 and Operand 2 both must be the same as Result
     Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fsub-op ::= ssa-id `=` `spv.FRemOp` ssa-use, ssa-use
                           `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FRemOp %0, %1 : f32
     %5 = spv.FRemOp %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_IAddOp : SPV_ArithmeticBinaryOp<"IAdd", SPV_Integer, [Commutative]> {
   let summary = "Integer addition of Operand 1 and Operand 2.";
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same number of components as Result
     Type. They must have the same component width as Result Type.
 
     The resulting value will equal the low-order N bits of the correct
     result R, where N is the component width and R is computed with enough
     precision to avoid overflow and underflow.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     iadd-op ::= ssa-id `=` `spv.IAdd` ssa-use, ssa-use
                           `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.IAdd %0, %1 : i32
     %5 = spv.IAdd %2, %3 : vector<4xi32>
-
     ```
   }];
 
   let hasFolder = 1;
 }
 
 // -----
 
 def SPV_IMulOp : SPV_ArithmeticBinaryOp<"IMul", SPV_Integer, [Commutative]> {
   let summary = "Integer multiplication of Operand 1 and Operand 2.";
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same number of components as Result
     Type. They must have the same component width as Result Type.
 
     The resulting value will equal the low-order N bits of the correct
     result R, where N is the component width and R is computed with enough
     precision to avoid overflow and underflow.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     imul-op ::= ssa-id `=` `spv.IMul` ssa-use, ssa-use
                           `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.IMul %0, %1 : i32
     %5 = spv.IMul %2, %3 : vector<4xi32>
-
     ```
   }];
 
   let hasFolder = 1;
 }
 
 // -----
 
 def SPV_ISubOp : SPV_ArithmeticBinaryOp<"ISub", SPV_Integer, []> {
   let summary = "Integer subtraction of Operand 2 from Operand 1.";
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same number of components as Result
     Type. They must have the same component width as Result Type.
 
     The resulting value will equal the low-order N bits of the correct
     result R, where N is the component width and R is computed with enough
     precision to avoid overflow and underflow.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     isub-op ::= `spv.ISub` ssa-use, ssa-use
                           `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.ISub %0, %1 : i32
     %5 = spv.ISub %2, %3 : vector<4xi32>
-
     ```
   }];
 
   let hasFolder = 1;
 }
 
 // -----
 
 def SPV_SDivOp : SPV_ArithmeticBinaryOp<"SDiv", SPV_Integer, []> {
   let summary = "Signed-integer division of Operand 1 divided by Operand 2.";
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same number of components as Result
     Type. They must have the same component width as Result Type.
 
-     Results are computed per component.  The resulting value is undefined
     if Operand 2 is 0.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     sdiv-op ::= ssa-id `=` `spv.SDiv` ssa-use, ssa-use
                            `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.SDiv %0, %1 : i32
     %5 = spv.SDiv %2, %3 : vector<4xi32>
-
     ```
   }];
 }
 
 // -----
 
 def SPV_SModOp : SPV_ArithmeticBinaryOp<"SMod", SPV_Integer, []> {
   let summary = [{
     Signed remainder operation for the remainder whose sign matches the sign
     of Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same number of components as Result
     Type. They must have the same component width as Result Type.
 
-     Results are computed per component.  The resulting value is undefined
     if Operand 2 is 0.  Otherwise, the result is the remainder r of Operand
     1 divided by Operand 2 where if r ≠ 0, the sign of r is the same as the
     sign of Operand 2.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     smod-op ::= ssa-id `=` `spv.SMod` ssa-use, ssa-use
                            `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.SMod %0, %1 : i32
     %5 = spv.SMod %2, %3 : vector<4xi32>
-
     ```
   }];
 }
 
 // -----
 
 def SPV_SRemOp : SPV_ArithmeticBinaryOp<"SRem", SPV_Integer, []> {
   let summary = [{
     Signed remainder operation for the remainder whose sign matches the sign
     of Operand 1.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same number of components as Result
     Type. They must have the same component width as Result Type.
 
-     Results are computed per component.  The resulting value is undefined
     if Operand 2 is 0.  Otherwise, the result is the remainder r of Operand
     1 divided by Operand 2 where if r ≠ 0, the sign of r is the same as the
     sign of Operand 1.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     srem-op ::= ssa-id `=` `spv.SRem` ssa-use, ssa-use
                            `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.SRem %0, %1 : i32
     %5 = spv.SRem %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_UDivOp : SPV_ArithmeticBinaryOp<"UDiv", SPV_Integer, []> {
   let summary = "Unsigned-integer division of Operand 1 divided by Operand 2.";
 
   let description = [{
     Result Type must be a scalar or vector of integer type, whose Signedness
     operand is 0.
 
-     The types of Operand 1 and Operand 2 both must be the same as Result
-    Type.
+    The types of Operand 1 and Operand 2 both must be the same as Result Type.
 
-     Results are computed per component.  The resulting value is undefined
     if Operand 2 is 0.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     udiv-op ::= ssa-id `=` `spv.UDiv` ssa-use, ssa-use
                            `:` integer-scalar-vector-type
     ```
-    For example:
+
+    Example:
 
     ```
     %4 = spv.UDiv %0, %1 : i32
     %5 = spv.UDiv %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_UModOp : SPV_ArithmeticBinaryOp<"UMod", SPV_Integer> {
   let summary = "Unsigned modulo operation of Operand 1 modulo Operand 2.";
 
   let description = [{
     Result Type must be a scalar or vector of integer type, whose Signedness
     operand is 0.
 
-     The types of Operand 1 and Operand 2 both must be the same as Result
-    Type.
+    The types of Operand 1 and Operand 2 both must be the same as Result Type.
 
-     Results are computed per component.  The resulting value is undefined
     if Operand 2 is 0.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     umod-op ::= ssa-id `=` `spv.UMod` ssa-use, ssa-use
                            `:` integer-scalar-vector-type
     ```
-    For example:
+
+    Example:
 
     ```
     %4 = spv.UMod %0, %1 : i32
     %5 = spv.UMod %2, %3 : vector<4xi32>
-
     ```
   }];
 }
 
 #endif // SPIRV_ARITHMETIC_OPS

mlir/include/mlir/Dialect/SPIRV/SPIRVAtomicOps.td

let description = [{
     2) get a New Value by the bitwise AND of Original Value and Value, and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
     value pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     scope ::= `"CrossDevice"` | `"Device"` | `"Workgroup"` | ...
 
     memory-semantics ::= `"None"` | `"Acquire"` | "Release"` | ...
 
     atomic-and-op ::=
         `spv.AtomicAnd` scope memory-semantics
                         ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicAnd "Device" "None" %pointer, %value :
                        !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
 
     ```
     atomic-compare-exchange-weak-op ::=
         `spv.AtomicCompareExchangeWeak` scope memory-semantics memory-semantics
                                         ssa-use `,` ssa-use `,` ssa-use
                                         `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicCompareExchangeWeak "Workgroup" "Acquire" "None"
                                        %pointer, %value, %comparator
                                        : !spv.ptr<i32, WorkGroup>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
let description = [{
     2) get a New Value by integer addition of Original Value and Value, and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
     value pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     atomic-iadd-op ::=
         `spv.AtomicIAdd` scope memory-semantics
                          ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicIAdd "Device" "None" %pointer, %value :
                         !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     ### Custom assembly form
 
     ```
     atomic-idecrement-op ::=
         `spv.AtomicIDecrement` scope memory-semantics ssa-use
                                `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicIDecrement "Device" "None" %pointer :
                               !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     ### Custom assembly form
 
     ```
     atomic-iincrement-op ::=
         `spv.AtomicIIncrement` scope memory-semantics ssa-use
                                `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicIncrement "Device" "None" %pointer :
                              !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
-    value pointed to by Pointer must be the same as Result Type.
+    The type of Value must be the same as Result Type. The type of the value
+    pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     atomic-isub-op ::=
         `spv.AtomicISub` scope memory-semantics
                          ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicISub "Device" "None" %pointer, %value :
                         !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     2) get a New Value by the bitwise OR of Original Value and Value, and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
     value pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     atomic-or-op ::=
         `spv.AtomicOr` scope memory-semantics
                        ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicOr "Device" "None" %pointer, %value :
                       !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     Value and Value, and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
     value pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     atomic-smax-op ::=
         `spv.AtomicSMax` scope memory-semantics
                          ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicSMax "Device" "None" %pointer, %value :
                         !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     Value and Value, and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
     value pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     atomic-smin-op ::=
         `spv.AtomicSMin` scope memory-semantics
                          ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicSMin "Device" "None" %pointer, %value :
                         !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     Value and Value, and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
     value pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     atomic-umax-op ::=
         `spv.AtomicUMax` scope memory-semantics
                          ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicUMax "Device" "None" %pointer, %value :
                         !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     Value and Value, and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
     value pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     atomic-umin-op ::=
         `spv.AtomicUMin` scope memory-semantics
                          ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicUMin "Device" "None" %pointer, %value :
                         !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
let description = [{
     Value, and
 
     3) store the New Value back through Pointer.
 
     The instruction’s result is the Original Value.
 
     Result Type must be an integer type scalar.
 
-     The type of Value must be the same as Result Type.  The type of the
     value pointed to by Pointer must be the same as Result Type.
 
     Memory must be a valid memory Scope.
 
     ### Custom assembly form
 
     ```
     atomic-xor-op ::=
         `spv.AtomicXor` scope memory-semantics
                         ssa-use `,` ssa-use `:` spv-pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.AtomicXor "Device" "None" %pointer, %value :
                        !spv.ptr<i32, StorageBuffer>
     ```
   }];
 }
 
 // -----
 
 #endif // SPIRV_ATOMIC_OPS

mlir/include/mlir/Dialect/SPIRV/SPIRVBitOps.td

 }
 
 // -----
 
 def SPV_BitCountOp : SPV_BitUnaryOp<"BitCount", []> {
   let summary = "Count the number of set bits in an object.";
 
   let description = [{
-     Results are computed per component.
 
     Result Type must be a scalar or vector of integer type.  The components
     must be wide enough to hold the unsigned Width of Base as an unsigned
     value. That is, no sign bit is needed or counted when checking for a
     wide enough result width.
 
     Base must be a scalar or vector of integer type.  It must have the same
     number of components as Result Type.
 
     The result is the unsigned value that is the number of bits in Base that
     are 1.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                   `vector<` integer-literal `x` integer-type `>`
     bitcount-op ::= ssa-id `=` `spv.BitCount` ssa-use
                                `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.BitCount %0: i32
     %3 = spv.BitCount %1: vector<4xi32>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[]>
   ];
 }
 
 // -----
 
 def SPV_BitFieldInsertOp : SPV_Op<"BitFieldInsert",
     [NoSideEffect, AllTypesMatch<["base", "insert", "result"]>]> {
   let summary = [{
     Make a copy of an object, with a modified bit field that comes from
     another object.
   }];
 
   let description = [{
-     Results are computed per component.
 
     Result Type must be a scalar or vector of integer type.
 
-     The type of Base and Insert must be the same as Result Type.
 
     Any result bits numbered outside [Offset, Offset + Count -  1]
     (inclusive) will come from the corresponding bits in Base.
 
     Any result bits numbered in [Offset, Offset + Count -  1] come, in
     order, from the bits numbered [0, Count - 1] of Insert.
 
     Count  must be an integer type scalar. Count is the number of bits taken
     from Insert. It will be consumed as an unsigned value. Count can be 0,
     in which case the result will be Base.
 
     Offset  must be an integer type scalar. Offset is the lowest-order bit
     of the bit field.  It will be consumed as an unsigned value.
 
     The resulting value is undefined if Count or Offset or their sum is
     greater than the number of bits in the result.
 
-    ### Custom assembly form
-
-    ```
-    integer-scalar-vector-type ::= integer-type |
-                                  `vector<` integer-literal `x` integer-type `>`
-    bitfield-insert-op ::= ssa-id `=` `spv.BitFieldInsert` ssa-use `,` ssa-use
-                                      `,` ssa-use `,` ssa-use
-                                      `:` integer-scalar-vector-type
-                                      `,` integer-type `,` integer-type
-    ```
-
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.BitFieldInsert %base, %insert, %offset, %count : vector<3xi32>, i8, i8
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,

 }
 
 // -----
 
 def SPV_BitFieldSExtractOp : SPV_BitFieldExtractOp<"BitFieldSExtract", []> {
   let summary = "Extract a bit field from an object, with sign extension.";
 
   let description = [{
-     Results are computed per component.
 
     Result Type must be a scalar or vector of integer type.
 
-     The type of Base must be the same as Result Type.
 
     If Count is greater than 0: The bits of Base numbered in [Offset, Offset
     + Count -  1] (inclusive) become the bits numbered [0, Count - 1] of the
     result. The remaining bits of the result will all be the same as bit
     Offset + Count -  1 of Base.
 
     Count  must be an integer type scalar. Count is the number of bits
     extracted from Base. It will be consumed as an unsigned value. Count can
     be 0, in which case the result will be 0.
 
     Offset  must be an integer type scalar. Offset is the lowest-order bit
     of the bit field to extract from Base.  It will be consumed as an
     unsigned value.
 
     The resulting value is undefined if Count or Offset or their sum is
     greater than the number of bits in the result.
 
-    ### Custom assembly form
-
-    ```
-    integer-scalar-vector-type ::= integer-type |
-                                  `vector<` integer-literal `x` integer-type `>`
-    bitfield-extract-s-op ::= ssa-id `=` `spv.BitFieldSExtract` ssa-use
-                                         `,` ssa-use `,` ssa-use
-                                         `:` integer-scalar-vector-type
-                                         `,` integer-type `,` integer-type
-    ```
-
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.BitFieldSExtract %base, %offset, %count : vector<3xi32>, i8, i8
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[SPV_C_Shader]>
   ];
 }
 
 // -----
 
 def SPV_BitFieldUExtractOp : SPV_BitFieldExtractOp<"BitFieldUExtract", []> {
   let summary = "Extract a bit field from an object, without sign extension.";
 
   let description = [{
     The semantics are the same as with OpBitFieldSExtract with the exception
     that there is no sign extension. The remaining bits of the result will
     all be 0.
 
-    ### Custom assembly form
-
-    ```
-    integer-scalar-vector-type ::= integer-type |
-                                  `vector<` integer-literal `x` integer-type `>`
-    bitfield-extract-u-op ::= ssa-id `=` `spv.BitFieldUExtract` ssa-use
-                                         `,` ssa-use `,` ssa-use
-                                         `:` integer-scalar-vector-type
-                                         `,` integer-type `,` integer-type
-    ```
-
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.BitFieldUExtract %base, %offset, %count : vector<3xi32>, i8, i8
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[SPV_C_Shader]>
   ];
 }
 
 // -----
 
 def SPV_BitReverseOp : SPV_BitUnaryOp<"BitReverse", []> {
   let summary = "Reverse the bits in an object.";
 
   let description = [{
-     Results are computed per component.
 
     Result Type must be a scalar or vector of integer type.
 
-     The type of Base must be the same as Result Type.
 
     The bit-number n of the result will be taken from bit-number Width - 1 -
     n of Base, where Width is the OpTypeInt operand of the Result Type.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                    `vector<` integer-literal `x` integer-type `>`
     bitreverse-op ::= ssa-id `=` `spv.BitReverse` ssa-use
                                  `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.BitReverse %0 : i32
     %3 = spv.BitReverse %1 : vector<4xi32>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[SPV_C_Shader]>
   ];
 }
 
 // -----
 
 def SPV_BitwiseAndOp : SPV_BitBinaryOp<"BitwiseAnd", [Commutative]> {
   let summary = [{
     Result is 1 if both Operand 1 and Operand 2 are 1. Result is 0 if either
     Operand 1 or Operand 2 are 0.
   }];
 
   let description = [{
-     Results are computed per component, and within each component, per bit.
 
     Result Type must be a scalar or vector of integer type.  The type of
     Operand 1 and Operand 2  must be a scalar or vector of integer type.
     They must have the same number of components as Result Type. They must
     have the same component width as Result Type.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                   `vector<` integer-literal `x` integer-type `>`
     bitwise-and-op ::= ssa-id `=` `spv.BitwiseAnd` ssa-use, ssa-use
                                   `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.BitwiseAnd %0, %1 : i32
     %2 = spv.BitwiseAnd %0, %1 : vector<4xi32>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[]>
   ];
 }
 
 // -----
 
 def SPV_BitwiseOrOp : SPV_BitBinaryOp<"BitwiseOr", [Commutative]> {
   let summary = [{
     Result is 1 if either Operand 1 or Operand 2 is 1. Result is 0 if both
     Operand 1 and Operand 2 are 0.
   }];
 
   let description = [{
-     Results are computed per component, and within each component, per bit.
 
     Result Type must be a scalar or vector of integer type.  The type of
     Operand 1 and Operand 2  must be a scalar or vector of integer type.
     They must have the same number of components as Result Type. They must
     have the same component width as Result Type.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                   `vector<` integer-literal `x` integer-type `>`
     bitwise-or-op ::= ssa-id `=` `spv.BitwiseOr` ssa-use, ssa-use
                                   `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.BitwiseOr %0, %1 : i32
     %2 = spv.BitwiseOr %0, %1 : vector<4xi32>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[]>
   ];
 }
 
 // -----
 
 def SPV_BitwiseXorOp : SPV_BitBinaryOp<"BitwiseXor", [Commutative]> {
   let summary = [{
     Result is 1 if exactly one of Operand 1 or Operand 2 is 1. Result is 0
     if Operand 1 and Operand 2 have the same value.
   }];
 
   let description = [{
-     Results are computed per component, and within each component, per bit.
 
     Result Type must be a scalar or vector of integer type.  The type of
     Operand 1 and Operand 2  must be a scalar or vector of integer type.
     They must have the same number of components as Result Type. They must
     have the same component width as Result Type.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                   `vector<` integer-literal `x` integer-type `>`
     bitwise-xor-op ::= ssa-id `=` `spv.BitwiseXor` ssa-use, ssa-use
                                   `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.BitwiseXor %0, %1 : i32
     %2 = spv.BitwiseXor %0, %1 : vector<4xi32>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[]>
   ];
 }
 
 // -----
 
 def SPV_ShiftLeftLogicalOp : SPV_ShiftOp<"ShiftLeftLogical", []> {
   let summary = [{
     Shift the bits in Base left by the number of bits specified in Shift.
     The least-significant bits will be zero filled.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of each Base and Shift must be a scalar or vector of integer
     type. Base and Shift must have the same number of components.  The
     number of components and bit width of the type of Base must be the same
     as in Result Type.
 
     Shift is treated as unsigned. The result is undefined if Shift is
     greater than or equal to the bit width of the components of Base.
 
     The number of components and bit width of Result Type must match those
     Base type. All types must be integer types.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                   `vector<` integer-literal `x` integer-type `>`
     shift-left-logical-op ::= ssa-id `=` `spv.ShiftLeftLogical`
                                           ssa-use `,` ssa-use `:`
                                           integer-scalar-vector-type `,`
                                           integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.ShiftLeftLogical %0, %1 : i32, i16
     %5 = spv.ShiftLeftLogical %3, %4 : vector<3xi32>, vector<3xi16>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[]>
   ];
 }
 
 // -----
 
 def SPV_ShiftRightArithmeticOp : SPV_ShiftOp<"ShiftRightArithmetic", []> {
   let summary = [{
     Shift the bits in Base right by the number of bits specified in Shift.
     The most-significant bits will be filled with the sign bit from Base.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of each Base and Shift must be a scalar or vector of integer
     type. Base and Shift must have the same number of components.  The
     number of components and bit width of the type of Base must be the same
     as in Result Type.
 
     Shift is treated as unsigned. The result is undefined if Shift is
     greater than or equal to the bit width of the components of Base.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                   `vector<` integer-literal `x` integer-type `>`
     shift-right-arithmetic-op ::= ssa-id `=` `spv.ShiftRightArithmetic`
                                               ssa-use `,` ssa-use `:`
                                               integer-scalar-vector-type `,`
                                               integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.ShiftRightArithmetic %0, %1 : i32, i16
     %5 = spv.ShiftRightArithmetic %3, %4 : vector<3xi32>, vector<3xi16>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[]>
   ];
 }
 
 // -----
 
 def SPV_ShiftRightLogicalOp : SPV_ShiftOp<"ShiftRightLogical", []> {
   let summary = [{
     Shift the bits in Base right by the number of bits specified in Shift.
     The most-significant bits will be zero filled.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
-     The type of each Base and Shift must be a scalar or vector of integer
     type. Base and Shift must have the same number of components.  The
     number of components and bit width of the type of Base must be the same
     as in Result Type.
 
     Shift is consumed as an unsigned integer. The result is undefined if
     Shift is greater than or equal to the bit width of the components of
     Base.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                   `vector<` integer-literal `x` integer-type `>`
     shift-right-logical-op ::= ssa-id `=` `spv.ShiftRightLogical`
                                            ssa-use `,` ssa-use `:`
                                            integer-scalar-vector-type `,`
                                            integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.ShiftRightLogical %0, %1 : i32, i16
     %5 = spv.ShiftRightLogical %3, %4 : vector<3xi32>, vector<3xi16>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
     Capability<[]>
   ];
 }
 
 // -----
 
 def SPV_NotOp : SPV_BitUnaryOp<"Not", []> {
   let summary = "Complement the bits of Operand.";
 
   let description = [{
-     Results are computed per component, and within each component, per bit.
 
     Result Type must be a scalar or vector of integer type.
 
     Operand’s type  must be a scalar or vector of integer type.  It must
     have the same number of components as Result Type.  The component width
     must equal the component width in Result Type.
 
     ### Custom assembly form
 
     ```
     integer-scalar-vector-type ::= integer-type |
                                   `vector<` integer-literal `x` integer-type `>`
     not-op ::= ssa-id `=` `spv.BitNot` ssa-use `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.Not %0 : i32
     %3 = spv.Not %1 : vector<4xi32>
     ```
   }];
 }
 
 #endif // SPIRV_BIT_OPS

mlir/include/mlir/Dialect/SPIRV/SPIRVCastOps.td

let description = [{
 
     ### Custom assembly form
 
     ```
     bitcast-op ::= ssa-id `=` `spv.Bitcast` ssa-use
                    `:` operand-type `to` result-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.Bitcast %0 : f32 to i32
     %1 = spv.Bitcast %0 : vector<2xf32> to i64
     %1 = spv.Bitcast %0 : !spv.ptr<f32, Function> to !spv.ptr<i32, Function>
     ```
   }];
 
   let arguments = (ins
     SPV_ScalarOrVectorOrPtr:$operand
def SPV_ConvertFToSOp : SPV_CastOp<"ConvertFToS", SPV_Integer, SPV_Float, []> {
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
     Float Value must be a scalar or vector of floating-point type.  It must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     convert-f-to-s-op ::= ssa-id `=` `spv.ConvertFToSOp` ssa-use
                           `:` operand-type `to` result-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.ConvertFToS %0 : f32 to i32
     %3 = spv.ConvertFToS %2 : vector<3xf32> to vector<3xi32>
     ```
   }];
 }
 
 // -----
 
 def SPV_ConvertFToUOp : SPV_CastOp<"ConvertFToU", SPV_Integer, SPV_Float, []> {
   let summary = [{
     Convert value numerically from floating point to unsigned integer, with
     round toward 0.0.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type, whose Signedness
     operand is 0.
 
     Float Value must be a scalar or vector of floating-point type.  It must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     convert-f-to-u-op ::= ssa-id `=` `spv.ConvertFToUOp` ssa-use
                           `:` operand-type `to` result-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.ConvertFToU %0 : f32 to i32
     %3 = spv.ConvertFToU %2 : vector<3xf32> to vector<3xi32>
     ```
   }];
 }
 
 // -----
 
 def SPV_ConvertSToFOp : SPV_CastOp<"ConvertSToF", SPV_Float, SPV_Integer, []> {
   let summary = [{
     Convert value numerically from signed integer to floating point.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
     Signed Value must be a scalar or vector of integer type.  It must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     convert-s-to-f-op ::= ssa-id `=` `spv.ConvertSToFOp` ssa-use
                           `:` operand-type `to` result-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.ConvertSToF %0 : i32 to f32
     %3 = spv.ConvertSToF %2 : vector<3xi32> to vector<3xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_ConvertUToFOp : SPV_CastOp<"ConvertUToF", SPV_Float, SPV_Integer, []> {
   let summary = [{
     Convert value numerically from unsigned integer to floating point.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
     Unsigned Value must be a scalar or vector of integer type.  It must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     convert-u-to-f-op ::= ssa-id `=` `spv.ConvertUToFOp` ssa-use
                           `:` operand-type `to` result-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.ConvertUToF %0 : i32 to f32
     %3 = spv.ConvertUToF %2 : vector<3xi32> to vector<3xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FConvertOp : SPV_CastOp<"FConvert", SPV_Float, SPV_Float, []> {
   let summary = [{
     Convert value numerically from one floating-point width to another
     width.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of floating-point type.
 
     Float Value must be a scalar or vector of floating-point type.  It must
     have the same number of components as Result Type.  The component width
     cannot equal the component width in Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     f-convert-op ::= ssa-id `=` `spv.FConvertOp` ssa-use
                      `:` operand-type `to` result-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.FConvertOp %0 : f32 to f64
     %3 = spv.FConvertOp %2 : vector<3xf32> to vector<3xf64>
     ```
   }];
 
   let verifier = [{ return verifyCastOp(this->getOperation(), false); }];
 }
 
 // -----
 
 def SPV_SConvertOp : SPV_CastOp<"SConvert", SPV_Integer, SPV_Integer, []> {
   let summary = [{
     Convert signed width.  This is either a truncate or a sign extend.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type.
 
     Signed Value must be a scalar or vector of integer type.  It must have
     the same number of components as Result Type.  The component width
     cannot equal the component width in Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     s-convert-op ::= ssa-id `=` `spv.SConvertOp` ssa-use
                      `:` operand-type `to` result-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.SConvertOp %0 : i32 to i64
     %3 = spv.SConvertOp %2 : vector<3xi32> to vector<3xi64>
     ```
   }];
 
   let verifier = [{ return verifyCastOp(this->getOperation(), false); }];
 }
 
 // -----
 
 def SPV_UConvertOp : SPV_CastOp<"UConvert", SPV_Integer, SPV_Integer, []> {
   let summary = [{
     Convert unsigned width. This is either a truncate or a zero extend.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of integer type, whose Signedness
     operand is 0.
 
     Unsigned Value must be a scalar or vector of integer type.  It must have
     the same number of components as Result Type.  The component width
     cannot equal the component width in Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     u-convert-op ::= ssa-id `=` `spv.UConvertOp` ssa-use
                  `:` operand-type `to` result-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %1 = spv.UConvertOp %0 : i32 to i64
     %3 = spv.UConvertOp %2 : vector<3xi32> to vector<3xi64>
     ```
   }];
 
   let verifier = [{ return verifyCastOp(this->getOperation(), false); }];
 }
 
 #endif // SPIRV_CAST_OPS

mlir/include/mlir/Dialect/SPIRV/SPIRVCompositeOps.td

let description = [{
 
     ### Custom assembly form
 
     ```
     composite-construct-op ::= ssa-id `=` `spv.CompositeConstruct`
                                (ssa-use (`,` ssa-use)* )? `:` composite-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.CompositeConstruct %1, %2, %3 : vector<3xf32>
     ```
   }];
 
   let arguments = (ins
     Variadic<SPV_Type>:$constituents
   );
 
let description = [{
     ### Custom assembly form
 
     ```
     composite-extract-op ::= ssa-id `=` `spv.CompositeExtract` ssa-use
                              `[` integer-literal (',' integer-literal)* `]`
                              `:` composite-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.Variable : !spv.ptr<!spv.array<4x!spv.array<4xf32>>, Function>
     %1 = spv.Load "Function" %0 ["Volatile"] : !spv.array<4x!spv.array<4xf32>>
     %2 = spv.CompositeExtract %1[1 : i32] : !spv.array<4x!spv.array<4xf32>>
     ```
 
   }];
 
   let arguments = (ins
let description = [{
     ### Custom assembly form
 
     ```
     composite-insert-op ::= ssa-id `=` `spv.CompositeInsert` ssa-use, ssa-use
                             `[` integer-literal (',' integer-literal)* `]`
                             `:` object-type `into` composite-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.CompositeInsert %object, %composite[1 : i32] : f32 into !spv.array<4xf32>
     ```
   }];
 
   let arguments = (ins
     SPV_Type:$object,
     SPV_Composite:$composite,
     I32ArrayAttr:$indices
   );
 
   let results = (outs
     SPV_Composite:$result
   );
 }
 
 #endif // SPIRV_COMPOSITE_OPS

mlir/include/mlir/Dialect/SPIRV/SPIRVControlFlowOps.td

 def SPV_BranchOp : SPV_Op<"Branch", [
     DeclareOpInterfaceMethods<BranchOpInterface>, InFunctionScope, NoSideEffect,
     Terminator]> {
   let summary = "Unconditional branch to target block.";
 
   let description = [{
     This instruction must be the last instruction in a block.
 
-    ### Custom assembly form
-
-    ```
-    branch-op ::= `spv.Branch` successor
-    successor ::= bb-id branch-use-list?
-    branch-use-list ::= `(` ssa-use-list `:` type-list-no-parens `)`
-    ```
+    Example:
 
-    For example:
-
-    ```
+    ```mlir
     spv.Branch ^target
     spv.Branch ^target(%0, %1: i32, f32)
     ```
   }];
 
   let arguments = (ins Variadic<SPV_Type>:$targetOperands);
 
   let results = (outs);
let description = [{
     ```
     branch-conditional-op ::= `spv.BranchConditional` ssa-use
                               (`[` integer-literal, integer-literal `]`)?
                               `,` successor `,` successor
     successor ::= bb-id branch-use-list?
     branch-use-list ::= `(` ssa-use-list `:` type-list-no-parens `)`
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     spv.BranchConditional %condition, ^true_branch, ^false_branch
     spv.BranchConditional %condition, ^true_branch(%0: i32), ^false_branch(%1: i32)
     ```
   }];
 
   let arguments = (ins
     SPV_Bool:$condition,
     Variadic<SPV_Type>:$trueTargetOperands,
let description = [{
     reference.
 
     Argument N is the object to copy to parameter N of Function.
 
     Note: A forward call is possible because there is no missing type
     information: Result Type must match the Return Type of the function, and
     the calling argument types must match the formal parameter types.
 
-    ### Custom assembly form
+    Example:
 
-    ```
-    function-call-op ::= `spv.FunctionCall` function-id `(` ssa-use-list `)`
-                     `:` function-type
-    ```
-
-    For example:
-
-    ```
+    ```mlir
     spv.FunctionCall @f_void(%arg0) : (i32) ->  ()
     %0 = spv.FunctionCall @f_iadd(%arg0, %arg1) : (i32, i32) -> i32
     ```
   }];
 
   let arguments = (ins
     FlatSymbolRefAttr:$callee,
     Variadic<SPV_Type>:$arguments

 // -----
 
 def SPV_ReturnOp : SPV_Op<"Return", [InFunctionScope, NoSideEffect,
                                      Terminator]> {
   let summary = "Return with no value from a function with void return type.";
 
   let description = [{
     This instruction must be the last instruction in a block.
-
-    ### Custom assembly form
-
-    ```
-    return-op ::= `spv.Return`
-    ```
   }];
 
   let arguments = (ins);
 
   let results = (outs);
 
   let assemblyFormat = "attr-dict";
 }
 
 // -----
 
 def SPV_UnreachableOp : SPV_Op<"Unreachable", [InFunctionScope, Terminator]> {
   let summary = "Declares that this block is not reachable in the CFG.";
 
   let description = [{
     This instruction must be the last instruction in a block.
-
-    ### Custom assembly form
-
-    ```
-    unreachable-op ::= `spv.Unreachable`
-    ```
   }];
 
   let arguments = (ins);
 
   let results = (outs);
 
   let assemblyFormat = "attr-dict";
 }
 
 // -----
 
 def SPV_ReturnValueOp : SPV_Op<"ReturnValue", [InFunctionScope, NoSideEffect,
                                                Terminator]> {
   let summary = "Return a value from a function.";
 
   let description = [{
     Value is the value returned, by copy, and must match the Return Type
     operand of the OpTypeFunction type of the OpFunction body this return
     instruction is in.
 
     This instruction must be the last instruction in a block.
 
-    ### Custom assembly form
-
-    ```
-    return-value-op ::= `spv.ReturnValue` ssa-use `:` spirv-type
-    ```
-
-    For example:
+    Example:
 
     ```
     spv.ReturnValue %0 : f32
     ```
   }];
 
   let arguments = (ins
     SPV_Type:$value

mlir/include/mlir/Dialect/SPIRV/SPIRVGLSLOps.td

let description = [{
 
     The operand x must be a scalar or vector whose component type is
     floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     abs-op ::= ssa-id `=` `spv.GLSL.FAbs` ssa-use `:`
                float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.FAbs %0 : f32
     %3 = spv.GLSL.FAbs %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLSAbsOp : SPV_GLSLUnaryArithmeticOp<"SAbs", 5, SPV_Integer> {
   let summary = "Absolute value of operand";
 
   let description = [{
     Result is x if x ≥ 0; otherwise result is -x, where x is interpreted as a
     signed integer.
 
     Result Type and the type of x must both be integer scalar or integer vector
     types. Result Type and operand types must have the same number of components
     with the same component width. Results are computed per component.
 
     ### Custom assembly format
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                    `vector<` integer-literal `x` integer-type `>`
     abs-op ::= ssa-id `=` `spv.GLSL.SAbs` ssa-use `:`
                integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.SAbs %0 : i32
     %3 = spv.GLSL.SAbs %1 : vector<3xi16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLCeilOp : SPV_GLSLUnaryArithmeticOp<"Ceil", 9, SPV_Float> {
   let summary = "Rounds up to the next whole number";
 
   let description = [{
     Result is the value equal to the nearest whole number that is greater than
     or equal to x.
 
     The operand x must be a scalar or vector whose component type is
     floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     ceil-op ::= ssa-id `=` `spv.GLSL.Ceil` ssa-use `:`
                 float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.Ceil %0 : f32
     %3 = spv.GLSL.Ceil %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLCosOp : SPV_GLSLUnaryArithmeticOp<"Cos", 14, SPV_Float16or32> {
   let summary = "Cosine of operand in radians";
 
   let description = [{
     The standard trigonometric cosine of x radians.
 
     The operand x must be a scalar or vector whose component type is 16-bit or
     32-bit floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     restricted-float-scalar-type ::=  `f16` | `f32`
     restricted-float-scalar-vector-type ::=
       restricted-float-scalar-type |
       `vector<` integer-literal `x` restricted-float-scalar-type `>`
     cos-op ::= ssa-id `=` `spv.GLSL.Cos` ssa-use `:`
                restricted-float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.Cos %0 : f32
     %3 = spv.GLSL.Cos %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLSinOp : SPV_GLSLUnaryArithmeticOp<"Sin", 13, SPV_Float16or32> {
   let summary = "Sine of operand in radians";
 
   let description = [{
     The standard trigonometric sine of x radians.
 
     The operand x must be a scalar or vector whose component type is 16-bit or
     32-bit floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     restricted-float-scalar-type ::=  `f16` | `f32`
     restricted-float-scalar-vector-type ::=
       restricted-float-scalar-type |
       `vector<` integer-literal `x` restricted-float-scalar-type `>`
     sin-op ::= ssa-id `=` `spv.GLSL.Sin` ssa-use `:`
                restricted-float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.Sin %0 : f32
     %3 = spv.GLSL.Sin %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLExpOp : SPV_GLSLUnaryArithmeticOp<"Exp", 27, SPV_Float16or32> {
   let summary = "Exponentiation of Operand 1";
 
   let description = [{
     Result is the natural exponentiation of x; e^x.
 
     The operand x must be a scalar or vector whose component type is
     16-bit or 32-bit floating-point.
 
     Result Type and the type of x must be the same type. Results are
     computed per component.";
 
     ### Custom assembly format
+
     ```
     restricted-float-scalar-type ::=  `f16` | `f32`
     restricted-float-scalar-vector-type ::=
       restricted-float-scalar-type |
       `vector<` integer-literal `x` restricted-float-scalar-type `>`
     exp-op ::= ssa-id `=` `spv.GLSL.Exp` ssa-use `:`
                restricted-float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.Exp %0 : f32
     %3 = spv.GLSL.Exp %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLFloorOp : SPV_GLSLUnaryArithmeticOp<"Floor", 8, SPV_Float> {
   let summary = "Rounds down to the next whole number";
 
   let description = [{
     Result is the value equal to the nearest whole number that is less than or
     equal to x.
 
     The operand x must be a scalar or vector whose component type is
     floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     floor-op ::= ssa-id `=` `spv.GLSL.Floor` ssa-use `:`
                 float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.Floor %0 : f32
     %3 = spv.GLSL.Floor %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLInverseSqrtOp : SPV_GLSLUnaryArithmeticOp<"InverseSqrt", 32, SPV_Float> {
   let summary = "Reciprocal of sqrt(operand)";
 
   let description = [{
     Result is the reciprocal of sqrt x. Result is undefined if x <= 0.
 
     The operand x must be a scalar or vector whose component type is
     floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     rsqrt-op ::= ssa-id `=` `spv.GLSL.InverseSqrt` ssa-use `:`
                  float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.InverseSqrt %0 : f32
     %3 = spv.GLSL.InverseSqrt %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLLogOp : SPV_GLSLUnaryArithmeticOp<"Log", 28, SPV_Float16or32> {
   let summary = "Natural logarithm of the operand";
 
   let description = [{
     Result is the natural logarithm of x, i.e., the value y which satisfies the
     equation x = ey. Result is undefined if x <= 0.
 
     The operand x must be a scalar or vector whose component type is 16-bit or
     32-bit floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     restricted-float-scalar-type ::=  `f16` | `f32`
     restricted-float-scalar-vector-type ::=
       restricted-float-scalar-type |
       `vector<` integer-literal `x` restricted-float-scalar-type `>`
     log-op ::= ssa-id `=` `spv.GLSL.Log` ssa-use `:`
                restricted-float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.Log %0 : f32
     %3 = spv.GLSL.Log %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLFMaxOp : SPV_GLSLBinaryArithmeticOp<"FMax", 40, SPV_Float> {
   let summary = "Return maximum of two floating-point operands";
 
   let description = [{
     Result is y if x < y; otherwise result is x. Which operand is the
     result is undefined if one of the operands is a NaN.
 
     The operands must all be a scalar or vector whose component type
     is floating-point.
 
     Result Type and the type of all operands must be the same
     type. Results are computed per component.
 
     ### Custom assembly format
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fmax-op ::= ssa-id `=` `spv.GLSL.FMax` ssa-use `:`
                 float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.FMax %0, %1 : f32
     %3 = spv.GLSL.FMax %0, %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLSMaxOp : SPV_GLSLBinaryArithmeticOp<"SMax", 42, SPV_Integer> {
   let summary = "Return maximum of two signed integer operands";
 
   let description = [{
     Result is y if x < y; otherwise result is x, where x and y are interpreted
     as signed integers.
 
     Result Type and the type of x and y must both be integer scalar or integer
     vector types. Result Type and operand types must have the same number of
     components with the same component width. Results are computed per
     component.
 
     ### Custom assembly format
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                    `vector<` integer-literal `x` integer-type `>`
     smax-op ::= ssa-id `=` `spv.GLSL.SMax` ssa-use `:`
                 integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.SMax %0, %1 : i32
     %3 = spv.GLSL.SMax %0, %1 : vector<3xi16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLFMinOp : SPV_GLSLBinaryArithmeticOp<"FMin", 37, SPV_Float> {
   let summary = "Return minimum of two floating-point operands";
 
   let description = [{
     Result is y if y < x; otherwise result is x. Which operand is the result is
     undefined if one of the operands is a NaN.
 
     The operands must all be a scalar or vector whose component type is
     floating-point.
 
     Result Type and the type of all operands must be the same type. Results are
     computed per component.
 
     ### Custom assembly format
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fmin-op ::= ssa-id `=` `spv.GLSL.FMin` ssa-use `:`
                 float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.FMin %0, %1 : f32
     %3 = spv.GLSL.FMin %0, %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLSMinOp : SPV_GLSLBinaryArithmeticOp<"SMin", 39, SPV_Integer> {
   let summary = "Return minimum of two signed integer operands";
 
   let description = [{
     Result is y if y < x; otherwise result is x, where x and y are interpreted
     as signed integers.
 
     Result Type and the type of x and y must both be integer scalar or integer
     vector types. Result Type and operand types must have the same number of
     components with the same component width. Results are computed per
     component.
 
     ### Custom assembly format
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                    `vector<` integer-literal `x` integer-type `>`
     smin-op ::= ssa-id `=` `spv.GLSL.SMin` ssa-use `:`
                 integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.SMin %0, %1 : i32
     %3 = spv.GLSL.SMin %0, %1 : vector<3xi16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLFSignOp : SPV_GLSLUnaryArithmeticOp<"FSign", 6, SPV_Float> {
   let summary = "Returns the sign of the operand";
 
   let description = [{
     Result is 1.0 if x > 0, 0.0 if x = 0, or -1.0 if x < 0.
 
     The operand x must be a scalar or vector whose component type is
     floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     sign-op ::= ssa-id `=` `spv.GLSL.FSign` ssa-use `:`
                 float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.FSign %0 : f32
     %3 = spv.GLSL.FSign %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLSSignOp : SPV_GLSLUnaryArithmeticOp<"SSign", 7, SPV_Integer> {
   let summary = "Returns the sign of the operand";
 
   let description = [{
     Result is 1 if x > 0, 0 if x = 0, or -1 if x < 0, where x is interpreted as
     a signed integer.
 
     Result Type and the type of x must both be integer scalar or integer vector
     types. Result Type and operand types must have the same number of components
     with the same component width. Results are computed per component.
 
     ### Custom assembly format
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                    `vector<` integer-literal `x` integer-type `>`
     sign-op ::= ssa-id `=` `spv.GLSL.SSign` ssa-use `:`
                 integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.SSign %0 : i32
     %3 = spv.GLSL.SSign %1 : vector<3xi16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLSqrtOp : SPV_GLSLUnaryArithmeticOp<"Sqrt", 31, SPV_Float> {
   let summary = "Returns the square root of the operand";
 
   let description = [{
     Result is the square root of x. Result is undefined if x < 0.
 
     The operand x must be a scalar or vector whose component type is
     floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     sqrt-op ::= ssa-id `=` `spv.GLSL.Sqrt` ssa-use `:`
                 float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.Sqrt %0 : f32
     %3 = spv.GLSL.Sqrt %1 : vector<3xf16>
     ```
   }];
 }
 
 // -----
 
 def SPV_GLSLTanhOp : SPV_GLSLUnaryArithmeticOp<"Tanh", 21, SPV_Float16or32> {
   let summary = "Hyperbolic tangent of operand in radians";
 
   let description = [{
     Hyperbolic tangent of x radians.
 
     The operand x must be a scalar or vector whose component type is 16-bit or
     32-bit floating-point.
 
     Result Type and the type of x must be the same type. Results are computed
     per component.
 
     ### Custom assembly format
+
     ```
     restricted-float-scalar-type ::=  `f16` | `f32`
     restricted-float-scalar-vector-type ::=
       restricted-float-scalar-type |
       `vector<` integer-literal `x` restricted-float-scalar-type `>`
     tanh-op ::= ssa-id `=` `spv.GLSL.Tanh` ssa-use `:`
                 restricted-float-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %2 = spv.GLSL.Tanh %0 : f32
     %3 = spv.GLSL.Tanh %1 : vector<3xf16>
     ```
   }];
 }
 
 #endif // SPIRV_GLSL_OPS

mlir/include/mlir/Dialect/SPIRV/SPIRVGroupOps.td

let description = [{
 
     Result Type must be a 4 component vector of 32 bit integer types.
 
     Result is a set of bitfields where the first invocation is represented in bit
     0 of the first vector component and the last (up to SubgroupSize) is the
     higher bit number of the last bitmask needed to represent all bits of the
     subgroup invocations.
 
-    ### Custom assembly form
+    Example:
 
-    ```
-    subgroup-ballot-op ::= ssa-id `=` `spv.SubgroupBallotKHR`
-                                ssa-use `:` `vector` `<` 4 `x` `i32` `>`
-    ```
-
-    For example:
-
-    ```
+    ```mlir
     %0 = spv.SubgroupBallotKHR %predicate : vector<4xi32>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_0>,
     MaxVersion<SPV_V_1_5>,
     Extension<[SPV_KHR_shader_ballot]>,

mlir/include/mlir/Dialect/SPIRV/SPIRVLogicalOps.td

 // -----
 
 def SPV_FOrdEqualOp : SPV_LogicalBinaryOp<"FOrdEqual", SPV_Float, [Commutative]> {
   let summary = "Floating-point comparison for being ordered and equal.";
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fordequal-op ::= ssa-id `=` `spv.FOrdEqual` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FOrdEqual %0, %1 : f32
     %5 = spv.FOrdEqual %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FOrdGreaterThanOp : SPV_LogicalBinaryOp<"FOrdGreaterThan", SPV_Float, []> {
   let summary = [{
     Floating-point comparison if operands are ordered and Operand 1 is
     greater than  Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fordgt-op ::= ssa-id `=` `spv.FOrdGreaterThan` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FOrdGreaterThan %0, %1 : f32
     %5 = spv.FOrdGreaterThan %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FOrdGreaterThanEqualOp : SPV_LogicalBinaryOp<"FOrdGreaterThanEqual", SPV_Float, []> {
   let summary = [{
     Floating-point comparison if operands are ordered and Operand 1 is
     greater than or equal to Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fordgte-op ::= ssa-id `=` `spv.FOrdGreaterThanEqual` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FOrdGreaterThanEqual %0, %1 : f32
     %5 = spv.FOrdGreaterThanEqual %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FOrdLessThanOp : SPV_LogicalBinaryOp<"FOrdLessThan", SPV_Float, []> {
   let summary = [{
     Floating-point comparison if operands are ordered and Operand 1 is less
     than Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fordlt-op ::= ssa-id `=` `spv.FOrdLessThan` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FOrdLessThan %0, %1 : f32
     %5 = spv.FOrdLessThan %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FOrdLessThanEqualOp : SPV_LogicalBinaryOp<"FOrdLessThanEqual", SPV_Float, []> {
   let summary = [{
     Floating-point comparison if operands are ordered and Operand 1 is less
     than or equal to Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fordlte-op ::= ssa-id `=` `spv.FOrdLessThanEqual` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FOrdLessThanEqual %0, %1 : f32
     %5 = spv.FOrdLessThanEqual %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FOrdNotEqualOp : SPV_LogicalBinaryOp<"FOrdNotEqual", SPV_Float, [Commutative]> {
   let summary = "Floating-point comparison for being ordered and not equal.";
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     fordneq-op ::= ssa-id `=` `spv.FOrdNotEqual` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FOrdNotEqual %0, %1 : f32
     %5 = spv.FOrdNotEqual %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FUnordEqualOp : SPV_LogicalBinaryOp<"FUnordEqual", SPV_Float, [Commutative]> {
   let summary = "Floating-point comparison for being unordered or equal.";
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     funordequal-op ::= ssa-id `=` `spv.FUnordEqual` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FUnordEqual %0, %1 : f32
     %5 = spv.FUnordEqual %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FUnordGreaterThanOp : SPV_LogicalBinaryOp<"FUnordGreaterThan", SPV_Float, []> {
   let summary = [{
     Floating-point comparison if operands are unordered or Operand 1 is
     greater than  Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     funordgt-op ::= ssa-id `=` `spv.FUnordGreaterThan` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FUnordGreaterThan %0, %1 : f32
     %5 = spv.FUnordGreaterThan %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FUnordGreaterThanEqualOp : SPV_LogicalBinaryOp<"FUnordGreaterThanEqual", SPV_Float, []> {
   let summary = [{
     Floating-point comparison if operands are unordered or Operand 1 is
     greater than or equal to Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     funordgte-op ::= ssa-id `=` `spv.FUnordGreaterThanEqual` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FUnordGreaterThanEqual %0, %1 : f32
     %5 = spv.FUnordGreaterThanEqual %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FUnordLessThanOp : SPV_LogicalBinaryOp<"FUnordLessThan", SPV_Float, []> {
   let summary = [{
     Floating-point comparison if operands are unordered or Operand 1 is less
     than Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     funordlt-op ::= ssa-id `=` `spv.FUnordLessThan` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FUnordLessThan %0, %1 : f32
     %5 = spv.FUnordLessThan %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FUnordLessThanEqualOp : SPV_LogicalBinaryOp<"FUnordLessThanEqual", SPV_Float, []> {
   let summary = [{
     Floating-point comparison if operands are unordered or Operand 1 is less
     than or equal to Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     funordlte-op ::= ssa-id `=` `spv.FUnordLessThanEqual` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FUnordLessThanEqual %0, %1 : f32
     %5 = spv.FUnordLessThanEqual %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_FUnordNotEqualOp : SPV_LogicalBinaryOp<"FUnordNotEqual", SPV_Float, [Commutative]> {
   let summary = "Floating-point comparison for being unordered or not equal.";
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     floating-point type.  They must have the same type, and they must have
     the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     funordneq-op ::= ssa-id `=` `spv.FUnordNotEqual` ssa-use, ssa-use
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %4 = spv.FUnordNotEqual %0, %1 : f32
     %5 = spv.FUnordNotEqual %2, %3 : vector<4xf32>
     ```
   }];
 }
 
 // -----
 
 def SPV_IEqualOp : SPV_LogicalBinaryOp<"IEqual", SPV_Integer, [Commutative]> {
   let summary = "Integer comparison for equality.";
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     iequal-op ::= ssa-id `=` `spv.IEqual` ssa-use, ssa-use
                              `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.IEqual %0, %1 : i32
     %5 = spv.IEqual %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_INotEqualOp : SPV_LogicalBinaryOp<"INotEqual", SPV_Integer, [Commutative]> {
   let summary = "Integer comparison for inequality.";
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     inot-equal-op ::= ssa-id `=` `spv.INotEqual` ssa-use, ssa-use
                                  `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.INotEqual %0, %1 : i32
     %5 = spv.INotEqual %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_LogicalAndOp : SPV_LogicalBinaryOp<"LogicalAnd", SPV_Bool, [Commutative]> {
   let summary = [{
     Result is true if both Operand 1 and Operand 2 are true. Result is false
     if either Operand 1 or Operand 2 are false.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 must be the same as Result Type.
 
-     The type of Operand 2 must be the same as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     logical-and ::= `spv.LogicalAnd` ssa-use `,` ssa-use
                     `:` operand-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.LogicalAnd %0, %1 : i1
     %2 = spv.LogicalAnd %0, %1 : vector<4xi1>
     ```
   }];
 
   let hasFolder = 1;
 }
 
 // -----
 
 def SPV_LogicalEqualOp : SPV_LogicalBinaryOp<"LogicalEqual", SPV_Bool, [Commutative]> {
   let summary = [{
     Result is true if Operand 1 and Operand 2 have the same value. Result is
     false if Operand 1 and Operand 2 have different values.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 must be the same as Result Type.
 
-     The type of Operand 2 must be the same as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     logical-equal ::= `spv.LogicalEqual` ssa-use `,` ssa-use
                       `:` operand-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.LogicalEqual %0, %1 : i1
     %2 = spv.LogicalEqual %0, %1 : vector<4xi1>
     ```
   }];
 }
 
 // -----
 
 def SPV_LogicalNotOp : SPV_LogicalUnaryOp<"LogicalNot", SPV_Bool, []> {
   let summary = [{
     Result is true if Operand is false.  Result is false if Operand is true.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand must be the same as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     logical-not ::= `spv.LogicalNot` ssa-use `:` operand-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.LogicalNot %0 : i1
     %2 = spv.LogicalNot %0 : vector<4xi1>
     ```
   }];
 
   let hasCanonicalizer = 1;
 }
 
 // -----
 
 def SPV_LogicalNotEqualOp : SPV_LogicalBinaryOp<"LogicalNotEqual", SPV_Bool, [Commutative]> {
   let summary = [{
     Result is true if Operand 1 and Operand 2 have different values. Result
     is false if Operand 1 and Operand 2 have the same value.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 must be the same as Result Type.
 
-     The type of Operand 2 must be the same as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     logical-not-equal ::= `spv.LogicalNotEqual` ssa-use `,` ssa-use
                           `:` operand-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.LogicalNotEqual %0, %1 : i1
     %2 = spv.LogicalNotEqual %0, %1 : vector<4xi1>
     ```
   }];
 }
 
 // -----
 
 def SPV_LogicalOrOp : SPV_LogicalBinaryOp<"LogicalOr", SPV_Bool, [Commutative]> {
   let summary = [{
     Result is true if either Operand 1 or Operand 2 is true. Result is false
     if both Operand 1 and Operand 2 are false.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 must be the same as Result Type.
 
-     The type of Operand 2 must be the same as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
 
     ```
     logical-or ::= `spv.LogicalOr` ssa-use `,` ssa-use
                     `:` operand-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %2 = spv.LogicalOr %0, %1 : i1
     %2 = spv.LogicalOr %0, %1 : vector<4xi1>
     ```
   }];
 
   let hasFolder = 1;
 }
 
 // -----
 
 def SPV_SGreaterThanOp : SPV_LogicalBinaryOp<"SGreaterThan", SPV_Integer, []> {
   let summary = [{
     Signed-integer comparison if Operand 1 is greater than  Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     sgreater-than-op ::= ssa-id `=` `spv.SGreaterThan` ssa-use, ssa-use
                                     `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.SGreaterThan %0, %1 : i32
     %5 = spv.SGreaterThan %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_SGreaterThanEqualOp : SPV_LogicalBinaryOp<"SGreaterThanEqual", SPV_Integer, []> {
   let summary = [{
     Signed-integer comparison if Operand 1 is greater than or equal to
     Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     sgreater-than-equal-op ::= ssa-id `=` `spv.SGreaterThanEqual` ssa-use, ssa-use
                                           `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.SGreaterThanEqual %0, %1 : i32
     %5 = spv.SGreaterThanEqual %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_SLessThanOp : SPV_LogicalBinaryOp<"SLessThan", SPV_Integer, []> {
   let summary = [{
     Signed-integer comparison if Operand 1 is less than Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     sless-than-op ::= ssa-id `=` `spv.SLessThan` ssa-use, ssa-use
                                  `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.SLessThan %0, %1 : i32
     %5 = spv.SLessThan %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_SLessThanEqualOp : SPV_LogicalBinaryOp<"SLessThanEqual", SPV_Integer, []> {
   let summary = [{
     Signed-integer comparison if Operand 1 is less than or equal to Operand
     2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     sless-than-equal-op ::= ssa-id `=` `spv.SLessThanEqual` ssa-use, ssa-use
                                        `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.SLessThanEqual %0, %1 : i32
     %5 = spv.SLessThanEqual %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_SelectOp : SPV_Op<"Select",
     [NoSideEffect, AllTypesMatch<["true_value", "false_value", "result"]>]> {
   let summary = [{
     Select between two objects. Before version 1.4, results are only
     computed per component.
   }];
 
   let description = [{
     Before version 1.4, Result Type must be a pointer, scalar, or vector.
 
-     The types of Object 1 and Object 2 must be the same as Result Type.
 
     Condition must be a scalar or vector of Boolean type.
 
     If Condition is a scalar and true, the result is Object 1. If Condition
     is a scalar and false, the result is Object 2.
 
     If Condition is a vector, Result Type must be a vector with the same
     number of components as Condition and the result is a mix of Object 1
     and Object 2: When a component of Condition is true, the corresponding
     component in the result is taken from Object 1, otherwise it is taken
     from Object 2.
 
-    ### Custom assembly form
-
-    ```
-    scalar-type ::= integer-type | float-type | boolean-type
-    select-object-type ::= scalar-type
-                           | `vector<` integer-literal `x` scalar-type `>`
-                           | pointer-type
-    select-condition-type ::= boolean-type
-                              | `vector<` integer-literal `x` boolean-type `>`
-    select-op ::= ssa-id `=` `spv.Select` ssa-use, ssa-use, ssa-use
-                  `:` select-condition-type `,` select-object-type
-    ```
-
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %3 = spv.Select %0, %1, %2 : i1, f32
     %3 = spv.Select %0, %1, %2 : i1, vector<3xi32>
     %3 = spv.Select %0, %1, %2 : vector<3xi1>, vector<3xf32>
     ```
   }];
 
   let arguments = (ins
     SPV_ScalarOrVectorOf<SPV_Bool>:$condition,

 def SPV_UGreaterThanOp : SPV_LogicalBinaryOp<"UGreaterThan", SPV_Integer, []> {
   let summary = [{
     Unsigned-integer comparison if Operand 1 is greater than  Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     ugreater-than-op ::= ssa-id `=` `spv.UGreaterThan` ssa-use, ssa-use
                                     `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.UGreaterThan %0, %1 : i32
     %5 = spv.UGreaterThan %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_UGreaterThanEqualOp : SPV_LogicalBinaryOp<"UGreaterThanEqual", SPV_Integer, []> {
   let summary = [{
     Unsigned-integer comparison if Operand 1 is greater than or equal to
     Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     ugreater-than-equal-op ::= ssa-id `=` `spv.UGreaterThanEqual` ssa-use, ssa-use
                                           `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.UGreaterThanEqual %0, %1 : i32
     %5 = spv.UGreaterThanEqual %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_ULessThanOp : SPV_LogicalBinaryOp<"ULessThan", SPV_Integer, []> {
   let summary = [{
     Unsigned-integer comparison if Operand 1 is less than Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     uless-than-op ::= ssa-id `=` `spv.ULessThan` ssa-use, ssa-use
                                  `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.ULessThan %0, %1 : i32
     %5 = spv.ULessThan %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 // -----
 
 def SPV_ULessThanEqualOp :
   SPV_LogicalBinaryOp<"ULessThanEqual", SPV_Integer, []> {
   let summary = [{
     Unsigned-integer comparison if Operand 1 is less than or equal to
     Operand 2.
   }];
 
   let description = [{
     Result Type must be a scalar or vector of Boolean type.
 
-     The type of Operand 1 and Operand 2  must be a scalar or vector of
     integer type.  They must have the same component width, and they must
     have the same number of components as Result Type.
 
-     Results are computed per component.
 
     ### Custom assembly form
+
     ```
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     uless-than-equal-op ::= ssa-id `=` `spv.ULessThanEqual` ssa-use, ssa-use
                                        `:` integer-scalar-vector-type
     ```
-    For example:
 
-    ```
+    Example:
+
+    ```mlir
     %4 = spv.ULessThanEqual %0, %1 : i32
     %5 = spv.ULessThanEqual %2, %3 : vector<4xi32>
 
     ```
   }];
 }
 
 #endif // SPIRV_LOGICAL_OPS

mlir/include/mlir/Dialect/SPIRV/SPIRVNonUniformOps.td

let description = [{
     in the lowest bit of the first vector component and the last (up to the
     size of the group) is the higher bit number of the last bitmask needed
     to represent all bits of the group invocations.
 
     Execution must be Workgroup or Subgroup Scope.
 
     Predicate must be a Boolean type.
 
-    ### Custom assembly form
-
-    ```
-    scope ::= `"Workgroup"` | `"Subgroup"`
-    non-uniform-ballot-op ::= ssa-id `=` `spv.GroupNonUniformBallot` scope
-                              ssa-use `:` `vector` `<` 4 `x` `integer-type` `>`
-    ```
-
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.GroupNonUniformBallot "SubGroup" %predicate : vector<4xi32>
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_3>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
let summary = [{
     group, otherwise result is false.
   }];
 
   let description = [{
     Result Type must be a Boolean type.
 
     Execution must be Workgroup or Subgroup Scope.
 
-    ### Custom assembly form
-
-    ```
-    scope ::= `"Workgroup"` | `"Subgroup"`
-    non-uniform-elect-op ::= ssa-id `=` `spv.GroupNonUniformElect` scope
-                             `:` `i1`
-    ```
-
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.GroupNonUniformElect : i1
     ```
   }];
 
   let availability = [
     MinVersion<SPV_V_1_3>,
     MaxVersion<SPV_V_1_5>,
     Extension<[]>,
def SPV_GroupNonUniformFAddOp :
   let description = [{
     Result Type  must be a scalar or vector of floating-point type.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is 0. If Operation is ClusteredReduce,
     ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.  The method used to
     perform the group operation on the contributed Value(s) from active
     invocations is implementation defined.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     non-uniform-fadd-op ::= ssa-id `=` `spv.GroupNonUniformFAdd` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : f32
     %vector = ... : vector<4xf32>
     %0 = spv.GroupNonUniformFAdd "Workgroup" "Reduce" %scalar : f32
     %1 = spv.GroupNonUniformFAdd "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xf32>
     ```
   }];
 }
def SPV_GroupNonUniformFMaxOp :
   let description = [{
     Result Type  must be a scalar or vector of floating-point type.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is -INF. If Operation is ClusteredReduce,
     ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.  The method used to
     perform the group operation on the contributed Value(s) from active
     invocations is implementation defined. From the set of Value(s) provided
     by active invocations within a subgroup, if for any two Values one of
     them is a NaN, the other is chosen. If all Value(s) that are used by the
     current invocation are NaN, then the result is an undefined value.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     non-uniform-fmax-op ::= ssa-id `=` `spv.GroupNonUniformFMax` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : f32
     %vector = ... : vector<4xf32>
     %0 = spv.GroupNonUniformFMax "Workgroup" "Reduce" %scalar : f32
     %1 = spv.GroupNonUniformFMax "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xf32>
     ```
   }];
 }
def SPV_GroupNonUniformFMinOp :
   let description = [{
     Result Type  must be a scalar or vector of floating-point type.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is +INF. If Operation is ClusteredReduce,
     ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.  The method used to
     perform the group operation on the contributed Value(s) from active
     invocations is implementation defined. From the set of Value(s) provided
     by active invocations within a subgroup, if for any two Values one of
     them is a NaN, the other is chosen. If all Value(s) that are used by the
     current invocation are NaN, then the result is an undefined value.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     non-uniform-fmin-op ::= ssa-id `=` `spv.GroupNonUniformFMin` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : f32
     %vector = ... : vector<4xf32>
     %0 = spv.GroupNonUniformFMin "Workgroup" "Reduce" %scalar : f32
     %1 = spv.GroupNonUniformFMin "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xf32>
     ```
   }];
 }
def SPV_GroupNonUniformFMulOp :
   let description = [{
     Result Type  must be a scalar or vector of floating-point type.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is 1. If Operation is ClusteredReduce,
     ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.  The method used to
     perform the group operation on the contributed Value(s) from active
     invocations is implementation defined.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     float-scalar-vector-type ::= float-type |
                                  `vector<` integer-literal `x` float-type `>`
     non-uniform-fmul-op ::= ssa-id `=` `spv.GroupNonUniformFMul` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` float-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : f32
     %vector = ... : vector<4xf32>
     %0 = spv.GroupNonUniformFMul "Workgroup" "Reduce" %scalar : f32
     %1 = spv.GroupNonUniformFMul "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xf32>
     ```
   }];
 }
def SPV_GroupNonUniformIAddOp :
   let description = [{
     Result Type  must be a scalar or vector of integer type.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is 0. If Operation is ClusteredReduce,
     ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     non-uniform-iadd-op ::= ssa-id `=` `spv.GroupNonUniformIAdd` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : i32
     %vector = ... : vector<4xi32>
     %0 = spv.GroupNonUniformIAdd "Workgroup" "Reduce" %scalar : i32
     %1 = spv.GroupNonUniformIAdd "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xi32>
     ```
   }];
 }
def SPV_GroupNonUniformIMulOp :
   let description = [{
     Result Type  must be a scalar or vector of integer type.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is 1. If Operation is ClusteredReduce,
     ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     non-uniform-imul-op ::= ssa-id `=` `spv.GroupNonUniformIMul` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : i32
     %vector = ... : vector<4xi32>
     %0 = spv.GroupNonUniformIMul "Workgroup" "Reduce" %scalar : i32
     %1 = spv.GroupNonUniformIMul "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xi32>
     ```
   }];
 }
def SPV_GroupNonUniformSMaxOp :
   let description = [{
     Result Type  must be a scalar or vector of integer type.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is INT_MIN. If Operation is
     ClusteredReduce, ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     non-uniform-smax-op ::= ssa-id `=` `spv.GroupNonUniformSMax` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : i32
     %vector = ... : vector<4xi32>
     %0 = spv.GroupNonUniformSMax "Workgroup" "Reduce" %scalar : i32
     %1 = spv.GroupNonUniformSMax "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xi32>
     ```
   }];
 }
def SPV_GroupNonUniformSMinOp :
   let description = [{
     Result Type  must be a scalar or vector of integer type.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is INT_MAX. If Operation is
     ClusteredReduce, ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     non-uniform-smin-op ::= ssa-id `=` `spv.GroupNonUniformSMin` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : i32
     %vector = ... : vector<4xi32>
     %0 = spv.GroupNonUniformSMin "Workgroup" "Reduce" %scalar : i32
     %1 = spv.GroupNonUniformSMin "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xi32>
     ```
   }];
 }
let description = [{
     Result Type  must be a scalar or vector of integer type, whose
     Signedness operand is 0.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is 0. If Operation is ClusteredReduce,
     ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     non-uniform-umax-op ::= ssa-id `=` `spv.GroupNonUniformUMax` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : i32
     %vector = ... : vector<4xi32>
     %0 = spv.GroupNonUniformUMax "Workgroup" "Reduce" %scalar : i32
     %1 = spv.GroupNonUniformUMax "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xi32>
     ```
   }];
 }
let description = [{
     Result Type  must be a scalar or vector of integer type, whose
     Signedness operand is 0.
 
     Execution must be Workgroup or Subgroup Scope.
 
     The identity I for Operation is UINT_MAX. If Operation is
     ClusteredReduce, ClusterSize must be specified.
 
-     The type of Value must be the same as Result Type.
 
     ClusterSize is the size of cluster to use. ClusterSize must be a scalar
     of integer type, whose Signedness operand is 0. ClusterSize must come
     from a constant instruction. ClusterSize must be at least 1, and must be
     a power of 2. If ClusterSize is greater than the declared SubGroupSize,
     executing this instruction results in undefined behavior.
 
     ### Custom assembly form
 
     ```
     scope ::= `"Workgroup"` | `"Subgroup"`
     operation ::= `"Reduce"` | `"InclusiveScan"` | `"ExclusiveScan"` | ...
     integer-scalar-vector-type ::= integer-type |
                                  `vector<` integer-literal `x` integer-type `>`
     non-uniform-umin-op ::= ssa-id `=` `spv.GroupNonUniformUMin` scope operation
                             ssa-use ( `cluster_size` `(` ssa_use `)` )?
                             `:` integer-scalar-vector-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %four = spv.constant 4 : i32
     %scalar = ... : i32
     %vector = ... : vector<4xi32>
     %0 = spv.GroupNonUniformUMin "Workgroup" "Reduce" %scalar : i32
     %1 = spv.GroupNonUniformUMin "Subgroup" "ClusteredReduce" %vector cluster_size(%four) : vector<4xi32>
     ```
   }];
 }
 
 // -----
 
 #endif // SPIRV_NON_UNIFORM_OPS

mlir/include/mlir/Dialect/SPIRV/SPIRVOps.td

let description = [{
     Indexes walk the type hierarchy to the desired depth, potentially down
     to scalar granularity. The first index in Indexes will select the top-
     level member/element/component/element of the base composite. All
     composite constituents use zero-based numbering, as described by their
     OpType… instruction. The second index will apply similarly to that
     result, and so on. Once any non-composite type is reached, there must be
     no remaining (unused) indexes.
 
-     Each index in Indexes
+    Each index in Indexes:
 
     - must be a scalar integer type,
 
     - is treated as a signed count, and
 
     - must be an OpConstant when indexing into a structure.
 
     ### Custom assembly form
+
     ```
     access-chain-op ::= ssa-id `=` `spv.AccessChain` ssa-use
                         `[` ssa-use (',' ssa-use)* `]`
                         `:` pointer-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = "spv.constant"() { value = 1: i32} : () -> i32
     %1 = spv.Variable : !spv.ptr<!spv.struct<f32, !spv.array<4xf32>>, Function>
     %2 = spv.AccessChain %1[%0] : !spv.ptr<!spv.struct<f32, !spv.array<4xf32>>, Function>
     %3 = spv.Load "Function" %2 ["Volatile"] : !spv.array<4xf32>
     ```
   }];
 
   let arguments = (ins
let description = [{
     such restriction starting with version 1.3.
 
     When used with the TessellationControl execution model, it also
     implicitly synchronizes the Output Storage Class:  Writes to Output
     variables performed by any invocation executed prior to a
     OpControlBarrier will be visible to any other invocation after return
     from that OpControlBarrier.
 
-    ### Custom assembly form
-
-    ```
-    scope ::= `"CrossDevice"` | `"Device"` | `"Workgroup"` | ...
-
-    memory-semantics ::= `"None"` | `"Acquire"` | "Release"` | ...
-
-    control-barrier-op ::= `spv.ControlBarrier` scope, scope, memory-semantics
-    ```
-
-    For example:
+    Example:
 
-    ```
+    ```mlir
     spv.ControlBarrier "Workgroup", "Device", "Acquire|UniformMemory"
 
     ```
   }];
 
   let arguments = (ins
     SPV_ScopeAttr:$execution_scope,
     SPV_ScopeAttr:$memory_scope,
let description = [{
     ```
     execution-mode ::= "Invocations" | "SpacingEqual" |
                        <and other SPIR-V execution modes...>
 
     execution-mode-op ::= `spv.ExecutionMode ` ssa-use execution-mode
                           (integer-literal (`, ` integer-literal)* )?
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     spv.ExecutionMode @foo "ContractionOff"
     spv.ExecutionMode @bar "LocalSizeHint", 3, 4, 5
     ```
   }];
 
   let arguments = (ins
     FlatSymbolRefAttr:$fn,
     SPV_ExecutionModeAttr:$execution_mode,
let description = [{
     ```
     memory-access ::= `"None"` | `"Volatile"` | `"Aligned", ` integer-literal
                     | `"NonTemporal"`
 
     load-op ::= ssa-id ` = spv.Load ` storage-class ssa-use
                 (`[` memory-access `]`)? ` : ` spirv-element-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.Variable : !spv.ptr<f32, Function>
     %1 = spv.Load "Function" %0 : f32
     %2 = spv.Load "Function" %0 ["Volatile"] : f32
     %3 = spv.Load "Function" %0 ["Aligned", 4] : f32
     ```
   }];
 
   let arguments = (ins
let description = [{
     NonPrivateTexel image operand.
 
     Semantics declares what kind of memory is being controlled and what kind
     of control to apply.
 
     To execute both a memory barrier and a control barrier, see
     OpControlBarrier.
 
-    ### Custom assembly form
-
-    ```
-    scope ::= `"CrossDevice"` | `"Device"` | `"Workgroup"` | ...
-
-    memory-semantics ::= `"None"` | `"Acquire"` | `"Release"` | ...
-
-    memory-barrier-op ::= `spv.MemoryBarrier` scope, memory-semantics
-    ```
+    Example:
 
-    For example:
-
-    ```
+    ```mlir
     spv.MemoryBarrier "Device", "Acquire|UniformMemory"
 
     ```
   }];
 
   let arguments = (ins
     SPV_ScopeAttr:$memory_scope,
     SPV_MemorySemanticsAttr:$memory_semantics
let description = [{
 
     ### Custom assembly form
 
     ```
     store-op ::= `spv.Store ` storage-class ssa-use `, ` ssa-use `, `
                   (`[` memory-access `]`)? `:` spirv-element-type
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.Variable : !spv.ptr<f32, Function>
     %1 = spv.FMul ... : f32
     spv.Store "Function" %0, %1 : f32
     spv.Store "Function" %0, %1 ["Volatile"] : f32
     spv.Store "Function" %0, %1 ["Aligned", 4] : f32
   }];
 
   let arguments = (ins
def SPV_UndefOp : SPV_Op<"undef", []> {
 
   let description = [{
     Result Type is the type of object to make.
 
     Each consumption of Result <id> yields an arbitrary, possibly different
     bit pattern or abstract value resulting in possibly different concrete,
     abstract, or opaque values.
 
-    ### Custom assembly form
-
-    ```
-    undef-op ::= `spv.undef` `:` spirv-type
-    ```
+    Example:
 
-    For example:
-
-    ```
+    ```mlir
     %0 = spv.undef : f32
     %1 = spv.undef : !spv.struct<!spv.array<4 x vector<4xi32>>>
     ```
   }];
 
   let arguments = (ins);
 
   let results = (outs
variable-op ::= ssa-id `=` `spv.Variable` (`init(` ssa-use `)`)?
                     (`built_in(` string-literal `)`)?
                     attribute-dict? `:` spirv-pointer-type
     ```
 
     where `init` specifies initializer and `bind` specifies the
     descriptor set and binding number. `built_in` specifies SPIR-V
     BuiltIn decoration associated with the op.
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.constant ...
 
     %1 = spv.Variable : !spv.ptr<f32, Function>
     %2 = spv.Variable init(%0): !spv.ptr<f32, Private>
     %3 = spv.Variable init(%0) bind(1, 2): !spv.ptr<f32, Uniform>
     %3 = spv.Variable built_in("GlobalInvocationID") : !spv.ptr<vector<3xi32>, Uniform>
     ```
   }];

mlir/include/mlir/Dialect/SPIRV/SPIRVStructureOps.td

let description = [{
     Variables in module scope are defined using symbol names. This op generates
     an SSA value that can be used to refer to the symbol within function scope
     for use in ops that expect an SSA value. This operation has no corresponding
     SPIR-V instruction; it's merely used for modelling purpose in the SPIR-V
     dialect. Since variables in module scope in SPIR-V dialect are of pointer
     type, this op returns a pointer type as well, and the type is the same as
     the variable referenced.
 
-    ### Custom assembly form
-
-    ```
-    spv-address-of-op ::= ssa-id `=` `spv._address_of` symbol-ref-id
-                                     `:` spirv-pointer-type
-    ```
-
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv._address_of @global_var : !spv.ptr<f32, Input>
     ```
   }];
 
   let arguments = (ins
     FlatSymbolRefAttr:$variable
   );
 
let description = [{
 
     ### Custom assembly form
 
     ```
     spv-constant-op ::= ssa-id `=` `spv.constant` attribute-value
                         (`:` spirv-type)?
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     %0 = spv.constant true
     %1 = spv.constant dense<[2, 3]> : vector<2xf32>
     %2 = spv.constant [dense<3.0> : vector<2xf32>] : !spv.array<1xvector<2xf32>>
     ```
 
     TODO(antiagainst): support constant structs
   }];
 
let description = [{
     ```
     execution-model ::= "Vertex" | "TesellationControl" |
                         <and other SPIR-V execution models...>
 
     entry-point-op ::= ssa-id `=` `spv.EntryPoint` execution-model
                        symbol-reference (`, ` symbol-reference)*
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     spv.EntryPoint "GLCompute" @foo
     spv.EntryPoint "Kernel" @foo, @var1, @var2
 
     ```
   }];
 
   let arguments = (ins
     SPV_ExecutionModelAttr:$execution_model,
let description = [{
     ### Custom assembly form
 
     ```
     spv-function-control ::= "None" | "Inline" | "DontInline" | ...
     spv-function-op ::= `spv.func` function-signature
                          spv-function-control region
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     spv.func @foo() -> () "None" { ... }
     spv.func @bar() -> () "Inline|Pure" { ... }
     ```
   }];
 
   let arguments = (ins
     TypeAttr:$type,
     StrAttr:$sym_name,
variable-op ::= `spv.globalVariable` spirv-type symbol-ref-id
                     (`built_in(` string-literal `)`)?
                     attribute-dict?
     ```
 
     where `initializer` specifies initializer and `bind` specifies the
     descriptor set and binding number. `built_in` specifies SPIR-V
     BuiltIn decoration associated with the op.
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     spv.globalVariable @var0 : !spv.ptr<f32, Input> @var0
     spv.globalVariable @var1 initializer(@var0) : !spv.ptr<f32, Output>
     spv.globalVariable @var2 bind(1, 2) : !spv.ptr<f32, Uniform>
     spv.globalVariable @var3 built_in("GlobalInvocationId") : !spv.ptr<vector<3xi32>, Input>
     ```
   }];
 
   let arguments = (ins
let description = [{
     addressing-model ::= `Logical` | `Physical32` | `Physical64` | ...
     memory-model ::= `Simple` | `GLSL450` | `OpenCL` | `Vulkan` | ...
     spv-module-op ::= `spv.module` addressing-model memory-model
                       (requires  spirv-vce-attribute)?
                       (`attributes` attribute-dict)?
                       region
     ```
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     spv.module Logical GLSL450  {}
 
     spv.module Logical Vulkan
         requires #spv.vce<v1.0, [Shader], [SPV_KHR_vulkan_memory_model]>
         attributes { some_additional_attr = ... } {
       spv.func @do_nothing() -> () {
         spv.Return
       }
def SPV_ReferenceOfOp : SPV_Op<"_reference_of", [NoSideEffect]> {
   let description = [{
     Specialization constant in module scope are defined using symbol names.
     This op generates an SSA value that can be used to refer to the symbol
     within function scope for use in ops that expect an SSA value.
     This operation has no corresponding SPIR-V instruction; it's merely used
     for modelling purpose in the SPIR-V dialect. This op's return type is
     the same as the specialization constant.
 
-    ### Custom assembly form
+    Example:
 
-    ```
-    spv-reference-of-op ::= ssa-id `=` `spv._reference_of` symbol-ref-id
-                                       `:` spirv-scalar-type
-    ```
-
-    For example:
-
-    ```
+    ```mlir
     %0 = spv._reference_of @spec_const : f32
     ```
   }];
 
   let arguments = (ins
     FlatSymbolRefAttr:$spec_const
   );
 
let description = [{
     spv-spec-constant-op ::= `spv.specConstant` symbol-ref-id
                              `spec_id(` integer `)`
                              `=` attribute-value (`:` spirv-type)?
     ```
 
     where `spec_id` specifies the SPIR-V SpecId decoration associated with
     the op.
 
-    For example:
+    Example:
 
-    ```
+    ```mlir
     spv.specConstant @spec_const1 = true
     spv.specConstant @spec_const2 spec_id(5) = 42 : i32
     ```
 
     TODO(antiagainst): support composite spec constants with another op
   }];
 
   let arguments = (ins