[mlir][NFC] Clean and Fix broken Affine documentation

[sotoshigoto]

Summary

• Modified single-quote to back-quote at op name, etc.
• Remove a duplicated affine.store op's doc
• Fix broken links
• Move Syntax of StoreOp and LoadOp from Affine.md to AffineOps.td

[bondhugula]

LGTM - thanks very much.

[dcaballe]

Thanks a lot for the contribution!

[bondhugula]

The patch has two whitespace errors. Can you please fix these? I can land it otherwise.

git diff --check HEAD~
mlir/include/mlir/Dialect/Affine/IR/AffineOps.td:510: trailing whitespace.
+    
mlir/include/mlir/Dialect/Affine/IR/AffineOps.td:877: trailing whitespace.
+

[sotoshigoto]

In D142858#4092590, @bondhugula wrote:

The patch has two whitespace errors. Can you please fix these? I can land it otherwise.

git diff --check HEAD~
mlir/include/mlir/Dialect/Affine/IR/AffineOps.td:510: trailing whitespace.
+    
mlir/include/mlir/Dialect/Affine/IR/AffineOps.td:877: trailing whitespace.
+

ok, i will fix these tomorrow.

[sotoshigoto]

Fix two whitespace errors

mlir/docs/Dialects/Affine.md

 The affine dialect imposes certain restrictions on dimension and symbolic
 identifiers to enable powerful analysis and transformation. An SSA value's use
 can be bound to a symbolic identifier if that SSA value is either 1. a region
 argument for an op with trait `AffineScope` (eg. `FuncOp`), 2. a value defined
 at the top level of an `AffineScope` op (i.e., immediately enclosed by the
 latter), 3. a value that dominates the `AffineScope` op enclosing the value's
 use, 4. the result of a
 constant operation, 5. the result of an
-[`affine.apply` operation](#affineapply-affineapplyop) that recursively takes as
+[`affine.apply` operation](#affineapply-mliraffineapplyop) that recursively takes as
 arguments any valid symbolic identifiers, or 6. the result of a
 [`dim` operation](MemRef.md/#memrefdim-mlirmemrefdimop) on either a memref that
 is an argument to a `AffineScope` op or a memref where the corresponding
 dimension is either static or a dynamic one in turn bound to a valid symbol.
 *Note:* if the use of an SSA value is not contained in any op with the
 `AffineScope` trait, only the rules 4-6 can be applied.
 
 Note that as a result of rule (3) above, symbol validity is sensitive to the
 location of the SSA use. Dimensions may be bound not only to anything that a
 symbol is bound to, but also to induction variables of enclosing
-[`affine.for`](#affinefor-affineforop) and
-[`affine.parallel`](#affineparallel-affineparallelop) operations, and the result
-of an [`affine.apply` operation](#affineapply-affineapplyop) (which recursively
+[`affine.for`](#affinefor-mliraffineforop) and
+[`affine.parallel`](#affineparallel-mliraffineparallelop) operations, and the result
+of an [`affine.apply` operation](#affineapply-mliraffineapplyop) (which recursively
 may use other dimensions and symbols).
 
 ### Affine Expressions
 
 Syntax:
 
 ```
 affine-expr ::= `(` affine-expr `)`

 with one or more symbols in its specification are known as "symbolic affine
 maps", and those with no symbols as "non-symbolic affine maps".
 
 **Context:** Affine maps are mathematical functions that transform a list of
 dimension indices and symbols into a list of results, with affine expressions
 combining the indices and symbols. Affine maps distinguish between
 [indices and symbols](#dimensions-and-symbols) because indices are inputs to the
 affine map when the map is called (through an operation such as
-[affine.apply](#affineapply-affineapplyop)), whereas symbols are bound when the
+[affine.apply](#affineapply-mliraffineapplyop)), whereas symbols are bound when the
 map is established (e.g. when a memref is formed, establishing a memory
-[layout map](Builtin.md/#layout-map)).
+[layout map](Builtin.md/#layout)).
 
 Affine maps are used for various core structures in MLIR. The restrictions we
 impose on their form allows powerful analysis and transformation, while keeping
 the representation closed with respect to several operations of interest.
 
 #### Named affine mappings
 
 Syntax:

 
 `d0` and `d1` correspond to dimensional identifiers of the set, while `s0` and
 `s1` are symbol identifiers.
 
 ## Operations
 
 [include "Dialects/AffineOps.md"]
 
-### 'affine.load' operation
-
-Syntax:
-
-```
-operation ::= ssa-id `=` `affine.load` ssa-use `[` multi-dim-affine-map-of-ssa-ids `]` `:` memref-type
-```
-
-The `affine.load` op reads an element from a memref, where the index for each
-memref dimension is an affine expression of loop induction variables and
-symbols. The output of 'affine.load' is a new value with the same type as the
-elements of the memref. An affine expression of loop IVs and symbols must be
-specified for each dimension of the memref. The keyword 'symbol' can be used to
-indicate SSA identifiers which are symbolic.
-
-Example:
-
-```mlir
-
-  Example 1:
-
-    %1 = affine.load %0[%i0 + 3, %i1 + 7] : memref<100x100xf32>
-
-  Example 2: Uses 'symbol' keyword for symbols '%n' and '%m'.
-
-    %1 = affine.load %0[%i0 + symbol(%n), %i1 + symbol(%m)]
-      : memref<100x100xf32>
-
-```
-
-### 'affine.store' operation
-
-Syntax:
-
-```
-operation ::= ssa-id `=` `affine.store` ssa-use, ssa-use `[` multi-dim-affine-map-of-ssa-ids `]` `:` memref-type
-```
-
-The `affine.store` op writes an element to a memref, where the index for each
-memref dimension is an affine expression of loop induction variables and
-symbols. The 'affine.store' op stores a new value which is the same type as the
-elements of the memref. An affine expression of loop IVs and symbols must be
-specified for each dimension of the memref. The keyword 'symbol' can be used to
-indicate SSA identifiers which are symbolic.
-
-Example:
-
-```mlir
-
-    Example 1:
-
-      affine.store %v0, %0[%i0 + 3, %i1 + 7] : memref<100x100xf32>
-
-    Example 2: Uses 'symbol' keyword for symbols '%n' and '%m'.
-
-      affine.store %v0, %0[%i0 + symbol(%n), %i1 + symbol(%m)]
-        : memref<100x100xf32>
-
-```
-
-### 'affine.dma_start' operation
+### `affine.dma_start` (mlir::AffineDmaStartOp)
 
 Syntax:
 
 ```
 operation ::= `affine.dma_start` ssa-use `[` multi-dim-affine-map-of-ssa-ids `]`, `[` multi-dim-affine-map-of-ssa-ids `]`, `[` multi-dim-affine-map-of-ssa-ids `]`, ssa-use `:` memref-type
 ```
 
 The `affine.dma_start` op starts a non-blocking DMA operation that transfers

 for each memref dimension must be an affine expression of loop induction
 variables and symbols. The optional stride arguments should be of 'index' type,
 and specify a stride for the slower memory space (memory space with a lower
 memory space id), transferring chunks of number_of_elements_per_stride every
 stride until %num_elements are transferred. Either both or no stride arguments
 should be specified. The value of 'num_elements' must be a multiple of
 'number_of_elements_per_stride'.
 
-Example:
+Example 1:
 
-```mlir
-For example, a DmaStartOp operation that transfers 256 elements of a memref
-'%src' in memory space 0 at indices [%i + 3, %j] to memref '%dst' in memory
-space 1 at indices [%k + 7, %l], would be specified as follows:
+For example, a `DmaStartOp` operation that transfers 256 elements of a memref
+`%src` in memory space 0 at indices `[%i + 3, %j]` to memref `%dst` in memory
+space 1 at indices `[%k + 7, %l]`, would be specified as follows:
 
-  %num_elements = arith.constant 256
-  %idx = arith.constant 0 : index
-  %tag = memref.alloc() : memref<1xi32, 4>
-  affine.dma_start %src[%i + 3, %j], %dst[%k + 7, %l], %tag[%idx],
-    %num_elements :
-      memref<40x128xf32, 0>, memref<2x1024xf32, 1>, memref<1xi32, 2>
+
+```mlir
+```
 
-  If %stride and %num_elt_per_stride are specified, the DMA is expected to
-  transfer %num_elt_per_stride elements every %stride elements apart from
-  memory space 0 until %num_elements are transferred.
+Example 2:
 
-  affine.dma_start %src[%i, %j], %dst[%k, %l], %tag[%idx], %num_elements,
-    %stride, %num_elt_per_stride : ...
+If `%stride` and `%num_elt_per_stride` are specified, the DMA is expected to
+transfer `%num_elt_per_stride` elements every `%stride elements` apart from
+memory space 0 until `%num_elements` are transferred.
+
+```mlir
 ```
 
-### 'affine.dma_wait' operation
+### `affine.dma_wait` (mlir::AffineDmaWaitOp)
 
 Syntax:
 
 ```
 operation ::= `affine.dma_wait` ssa-use `[` multi-dim-affine-map-of-ssa-ids `]`, ssa-use `:` memref-type
 ```
 
 The `affine.dma_start` op blocks until the completion of a DMA operation
-associated with the tag element '%tag[%index]'. %tag is a memref, and %index has
+associated with the tag element `%tag[%index]`. `%tag` is a memref, and `%index` has
 to be an index with the same restrictions as any load/store index. In
 particular, index for each memref dimension must be an affine expression of loop
-induction variables and symbols. %num_elements is the number of elements
-associated with the DMA operation. For example:
+induction variables and symbols. `%num_elements` is the number of elements
+associated with the DMA operation.
 
 Example:
 
 ```mlir
 affine.dma_start %src[%i, %j], %dst[%k, %l], %tag[%index], %num_elements :
   memref<2048xf32, 0>, memref<256xf32, 1>, memref<1xi32, 2>
 ...
 ...
 affine.dma_wait %tag[%index], %num_elements : memref<1xi32, 2>
 ```

mlir/include/mlir/Dialect/Affine/IR/AffineOps.td

 
 // Require regions to have affine.yield.
 def ImplicitAffineTerminator
     : SingleBlockImplicitTerminator<"AffineYieldOp">;
 
 def AffineApplyOp : Affine_Op<"apply", [Pure]> {
   let summary = "affine apply operation";
   let description = [{
-    The affine.apply operation applies an [affine mapping](#affine-expressions)
+    The `affine.apply` operation applies an [affine mapping](#affine-maps)
     to a list of SSA values, yielding a single SSA value. The number of
     dimension and symbol arguments to `affine.apply` must be equal to the
     respective number of dimensional and symbolic inputs to the affine mapping;
     the affine mapping has to be one-dimensional, and so the `affine.apply`
     operation always returns one value. The input operands and result must all
     have ‘index’ type.
 
     Example:
let description = [{
 
     lower-bound ::= `max`? affine-map-attribute dim-and-symbol-use-list | shorthand-bound
     upper-bound ::= `min`? affine-map-attribute dim-and-symbol-use-list | shorthand-bound
     shorthand-bound ::= ssa-id | `-`? integer-literal
     ```
 
     The `affine.for` operation represents an affine loop nest. It has one region
     containing its body. This region must contain one block that terminates with
-    [`affine.yield`](#affineyield-affineyieldop). *Note:* when
+    [`affine.yield`](#affineyield-mliraffineyieldop). *Note:* when
     `affine.for` is printed in custom format, the terminator is omitted. The
     block has one argument of [`index`](Builtin.md/#indextype) type that
     represents the induction variable of the loop.
 
     The `affine.for` operation executes its body a number of times iterating
     from a lower bound to an upper bound by a stride. The stride, represented by
     `step`, is a positive constant integer which defaults to "1" if not present.
     The lower and upper bounds specify a half-open range: the range includes the
code extraClassDeclarationBase = [{
 
     static StringRef getMapAttrStrName() { return "map"; }
   }];
 }
 
 def AffineLoadOp : AffineLoadOpBase<"load"> {
   let summary = "affine load operation";
   let description = [{
-    The "affine.load" op reads an element from a memref, where the index
+    Syntax:
+
+    ```
+    operation ::= ssa-id `=` `affine.load` ssa-use `[` multi-dim-affine-map-of-ssa-ids `]` `:` memref-type
+    ```
+
+    The `affine.load` op reads an element from a memref, where the index
     for each memref dimension is an affine expression of loop induction
-    variables and symbols. The output of 'affine.load' is a new value with the
+    variables and symbols. The output of `affine.load` is a new value with the
     same type as the elements of the memref. An affine expression of loop IVs
     and symbols must be specified for each dimension of the memref. The keyword
-    'symbol' can be used to indicate SSA identifiers which are symbolic.
+    `symbol` can be used to indicate SSA identifiers which are symbolic.
 
     Example 1:
 
     ```mlir
     %1 = affine.load %0[%i0 + 3, %i1 + 7] : memref<100x100xf32>
     ```
 
-    Example 2: Uses 'symbol' keyword for symbols '%n' and '%m'.
+    Example 2: Uses `symbol` keyword for symbols `%n` and `%m`.
 
     ```mlir
     %1 = affine.load %0[%i0 + symbol(%n), %i1 + symbol(%m)] : memref<100x100xf32>
     ```
   }];
 
   let results = (outs AnyType:$result);
 
let description = [{
     %0 = affine.min affine_map<(d0)[s0] -> (1000, d0 + 512, s0)> (%arg0)[%arg1]
     ```
   }];
 }
 
 def AffineMaxOp : AffineMinMaxOpBase<"max", [Pure]> {
   let summary = "max operation";
   let description = [{
-    The "max" operation computes the maximum value result from a multi-result
+    The `affine.max` operation computes the maximum value result from a multi-result
     affine map.
 
     Example:
 
     ```mlir
     %0 = affine.max (d0) -> (1000, d0 + 512) (%i0) : index
     ```
   }];
 }
 
 def AffineParallelOp : Affine_Op<"parallel",
     [AutomaticAllocationScope, ImplicitAffineTerminator, RecursivelySpeculatable,
      RecursiveMemoryEffects, DeclareOpInterfaceMethods<LoopLikeOpInterface>,
      MemRefsNormalizable]> {
   let summary = "multi-index parallel band operation";
   let description = [{
-    The "affine.parallel" operation represents a hyper-rectangular affine
+    The `affine.parallel` operation represents a hyper-rectangular affine
     parallel band, defining zero or more SSA values for its induction variables.
     It has one region capturing the parallel band body. The induction variables
     are represented as arguments of this region. These SSA values always have
     type index, which is the size of the machine word. The strides, represented
     by steps, are positive constant integers which defaults to "1" if not
     present. The lower and upper bounds specify a half-open range: the range
     includes the lower bound but does not include the upper bound. The body
-    region must contain exactly one block that terminates with "affine.yield".
+    region must contain exactly one block that terminates with `affine.yield`.
 
     The lower and upper bounds of a parallel operation are represented as an
     application of an affine mapping to a list of SSA values passed to the map.
     The same restrictions hold for these SSA values as for all bindings of SSA
     values to dimensions and symbols. The list of expressions in each map is
     interpreted according to the respective bounds group attribute. If a single
     expression belongs to the group, then the result of this expression is taken
     as a lower(upper) bound of the corresponding loop induction variable. If
     multiple expressions belong to the group, then the lower(upper) bound is the
     max(min) of these values obtained from these expressions. The loop band has
     as many loops as elements in the group bounds attributes.
 
-    Each value yielded by affine.yield will be accumulated/reduced via one of
+    Each value yielded by `affine.yield` will be accumulated/reduced via one of
     the reduction methods defined in the AtomicRMWKind enum.  The order of
     reduction is unspecified, and lowering may produce any valid ordering.
     Loops with a 0 trip count will produce as a result the identity value
     associated with each reduction (i.e. 0.0 for addf, 1.0 for mulf).  Assign
     reductions for loops with a trip count != 1 produces undefined results.
 
-    Note: Calling AffineParallelOp::build will create the required region and
+    Note: Calling `AffineParallelOp::build` will create the required region and
     block, and insert the required terminator if it is trivial (i.e. no values
     are yielded).  Parsing will also create the required region, block, and
     terminator, even when they are missing from the textual representation.
 
     Example (3x3 valid convolution):
 
     ```mlir
     func.func @conv_2d(%D : memref<100x100xf32>, %K : memref<3x3xf32>) -> (memref<98x98xf32>) {
def AffineParallelOp : Affine_Op<"parallel",
   let hasFolder = 1;
   let hasVerifier = 1;
 }
 
 def AffinePrefetchOp : Affine_Op<"prefetch",
   [DeclareOpInterfaceMethods<AffineMapAccessInterface>]> {
   let summary = "affine prefetch operation";
   let description = [{
-    The "affine.prefetch" op prefetches data from a memref location described
+    The `affine.prefetch` op prefetches data from a memref location described
     with an affine subscript similar to affine.load, and has three attributes:
     a read/write specifier, a locality hint, and a cache type specifier as shown
     below:
 
     ```mlir
     affine.prefetch %0[%i, %j + 5], read, locality<3>, data : memref<400x400xi32>
     ```
 
code extraClassDeclarationBase = [{
 
     static StringRef getMapAttrStrName() { return "map"; }
   }];
 }
 
 def AffineStoreOp : AffineStoreOpBase<"store"> {
   let summary = "affine store operation";
   let description = [{
-    The "affine.store" op writes an element to a memref, where the index
+    Syntax:
+
+    ```
+    operation ::= `affine.store` ssa-use, ssa-use `[` multi-dim-affine-map-of-ssa-ids `]` `:` memref-type
+    ```
+
+    The `affine.store` op writes an element to a memref, where the index
     for each memref dimension is an affine expression of loop induction
-    variables and symbols. The 'affine.store' op stores a new value which is the
+    variables and symbols. The `affine.store` op stores a new value which is the
     same type as the elements of the memref. An affine expression of loop IVs
     and symbols must be specified for each dimension of the memref. The keyword
-    'symbol' can be used to indicate SSA identifiers which are symbolic.
+    `symbol` can be used to indicate SSA identifiers which are symbolic.
 
     Example 1:
 
     ```mlir
     affine.store %v0, %0[%i0 + 3, %i1 + 7] : memref<100x100xf32>
     ```
 
-    Example 2: Uses 'symbol' keyword for symbols '%n' and '%m'.
+    Example 2: Uses `symbol` keyword for symbols `%n` and `%m`.
 
     ```mlir
     affine.store %v0, %0[%i0 + symbol(%n), %i1 + symbol(%m)] : memref<100x100xf32>
     ```
   }];
   let arguments = (ins AnyType:$value,
       Arg<AnyMemRef, "the reference to store to",
       [MemWrite]>:$memref,
def AffineStoreOp : AffineStoreOpBase<"store"> {
   let hasFolder = 1;
   let hasVerifier = 1;
 }
 
 def AffineYieldOp : Affine_Op<"yield", [Pure, Terminator, ReturnLike,
     MemRefsNormalizable]> {
   let summary = "Yield values to parent operation";
   let description = [{
-    "affine.yield" yields zero or more SSA values from an affine op region and
+    The `affine.yield` yields zero or more SSA values from an affine op region and
     terminates the region. The semantics of how the values yielded are used
     is defined by the parent operation.
-    If "affine.yield" has any operands, the operands must match the parent
+    If `affine.yield` has any operands, the operands must match the parent
     operation's results.
-    If the parent operation defines no values, then the "affine.yield" may be
+    If the parent operation defines no values, then the `affine.yield` may be
     left out in the custom syntax and the builders will insert one implicitly.
     Otherwise, it has to be present in the syntax to indicate which values are
     yielded.
-    ```
   }];
 
   let arguments = (ins Variadic<AnyType>:$operands);
 
   let builders = [
     OpBuilder<(ins), [{ build($_builder, $_state, std::nullopt); }]>
   ];
 
   let assemblyFormat = "attr-dict ($operands^ `:` type($operands))?";
   let hasVerifier = 1;
 }
 
 def AffineVectorLoadOp : AffineLoadOpBase<"vector_load"> {
   let summary = "affine vector load operation";
   let description = [{
-    The "affine.vector_load" is the vector counterpart of
-    [affine.load](#affineload-affineloadop). It reads a slice from a
+    The `affine.vector_load` is the vector counterpart of
+    [affine.load](#affineload-mliraffineloadop). It reads a slice from a
     [MemRef](Builtin.md/#memreftype), supplied as its first operand,
     into a [vector](Builtin.md/#vectortype) of the same base elemental type.
     The index for each memref dimension is an affine expression of loop induction
     variables and symbols. These indices determine the start position of the read
     within the memref. The shape of the return vector type determines the shape of
     the slice read from the memref. This slice is contiguous along the respective
     dimensions of the shape. Strided vector loads will be supported in the future.
     An affine expression of loop IVs and symbols must be specified for each
-    dimension of the memref. The keyword 'symbol' can be used to indicate SSA
+    dimension of the memref. The keyword `symbol` can be used to indicate SSA
     identifiers which are symbolic.
 
     Example 1: 8-wide f32 vector load.
 
     ```mlir
     %1 = affine.vector_load %0[%i0 + 3, %i1 + 7] : memref<100x100xf32>, vector<8xf32>
     ```
 
-    Example 2: 4-wide f32 vector load. Uses 'symbol' keyword for symbols '%n' and '%m'.
+    Example 2: 4-wide f32 vector load. Uses `symbol` keyword for symbols `%n` and `%m`.
 
     ```mlir
     %1 = affine.vector_load %0[%i0 + symbol(%n), %i1 + symbol(%m)] : memref<100x100xf32>, vector<4xf32>
     ```
 
     Example 3: 2-dim f32 vector load.
 
     ```mlir
     %1 = affine.vector_load %0[%i0, %i1] : memref<100x100xf32>, vector<2x8xf32>
     ```
 
     TODOs:
     * Add support for strided vector loads.
     * Consider adding a permutation map to permute the slice that is read from memory
-    (see [vector.transfer_read](../Vector/#vectortransfer_read-vectortransferreadop)).
+    (see [vector.transfer_read](../Vector/#vectortransfer_read-mlirvectortransferreadop)).
   }];
 
   let results = (outs AnyVector:$result);
 
   let builders = [
     /// Builds an affine vector load op with the specified map and operands.
     OpBuilder<(ins "VectorType":$resultType, "AffineMap":$map,
       "ValueRange":$operands)>,
def AffineVectorLoadOp : AffineLoadOpBase<"vector_load"> {
   let hasCanonicalizer = 1;
   let hasCustomAssemblyFormat = 1;
   let hasVerifier = 1;
 }
 
 def AffineVectorStoreOp : AffineStoreOpBase<"vector_store"> {
   let summary = "affine vector store operation";
   let description = [{
-    The "affine.vector_store" is the vector counterpart of
-    [affine.store](#affinestore-affinestoreop). It writes a
+    The `affine.vector_store` is the vector counterpart of
+    [affine.store](#affinestore-mliraffinestoreop). It writes a
     [vector](Builtin.md/#vectortype), supplied as its first operand,
     into a slice within a [MemRef](Builtin.md/#memreftype) of the same base
     elemental type, supplied as its second operand.
     The index for each memref dimension is an affine expression of loop
     induction variables and symbols. These indices determine the start position
     of the write within the memref. The shape of th input vector determines the
     shape of the slice written to the memref. This slice is contiguous along the
     respective dimensions of the shape. Strided vector stores will be supported
     in the future.
     An affine expression of loop IVs and symbols must be specified for each
-    dimension of the memref. The keyword 'symbol' can be used to indicate SSA
+    dimension of the memref. The keyword `symbol` can be used to indicate SSA
     identifiers which are symbolic.
 
     Example 1: 8-wide f32 vector store.
 
     ```mlir
     affine.vector_store %v0, %0[%i0 + 3, %i1 + 7] : memref<100x100xf32>, vector<8xf32>
     ```
 
-    Example 2: 4-wide f32 vector store. Uses 'symbol' keyword for symbols '%n' and '%m'.
+    Example 2: 4-wide f32 vector store. Uses `symbol` keyword for symbols `%n` and `%m`.
 
     ```mlir
     affine.vector_store %v0, %0[%i0 + symbol(%n), %i1 + symbol(%m)] : memref<100x100xf32>, vector<4xf32>
     ```
 
     Example 3: 2-dim f32 vector store.
 
     ```mlir
     affine.vector_store %v0, %0[%i0, %i1] : memref<100x100xf32>, vector<2x8xf32>
     ```
 
     TODOs:
     * Add support for strided vector stores.
     * Consider adding a permutation map to permute the slice that is written to memory
-    (see [vector.transfer_write](../Vector/#vectortransfer_write-vectortransferwriteop)).
+    (see [vector.transfer_write](../Vector/#vectortransfer_write-mlirvectortransferwriteop)).
   }];
 
   let arguments = (ins AnyVector:$value,
       Arg<AnyMemRef, "the reference to store to",
       [MemWrite]>:$memref,
       Variadic<Index>:$indices);
 
   let skipDefaultBuilders = 1;