[mlir][doc] Slightly clarify bufferization documentation

[rikhuijzer]

I was reading through the very well written Destination-Passing Style docs. Even though I know not much about compilers, I managed to understand it pretty well. A few things tripped me up though, which this PR suggests to rewrite:

1. Write buffer(%0) instead of buffer(%0). While reading, I first interpreted the text as "the buffer (%0)", whereas it should be interpreted as pseudocode for "a function that determines the buffer applied to %0". Quickly introducing it and moving the backticks around as this PR does should make this more clear. Also, I verified that MLIR does not contain any other occurences of "buffer(<BACKTICK>". It does contain many occurences of "buffer(" (without the backtick after the opening bracket), so this PR makes notation a bit more consistent.
2. Quotation marks slowed me down during reading, so I removed them. I think it's also clear without.
3. The outs from linalg was suddenly introduced. I've tried to clarify in as few words as possible that outs stands for outputs but suggestions are welcome.

[llvmbot]

@llvm/pr-subscribers-mlir

Author: Rik Huijzer (rikhuijzer)

Changes

I was reading through the very well written Destination-Passing Style docs. Even though I know not much about compilers, I managed to understand it pretty well. A few things tripped me up though, which this PR suggests to rewrite:

1. Write buffer(%0) instead of buffer(%0). While reading, I first interpreted the text as "the buffer (%0)", whereas it should be interpreted as pseudocode for "a function that determines the buffer applied to %0". Quickly introducing it and moving the backticks around as this PR does should make this more clear. Also, I verified that MLIR does not contain any other occurences of "buffer(<BACKTICK>". It does contain many occurences of "buffer(" (without the backtick after the opening bracket), so this PR makes notation a bit more consistent.
2. Quotation marks slowed me down during reading, so I removed them. I think it's also clear without.
3. The outs from linalg was suddenly introduced. I've tried to clarify in as few words as possible that outs stands for outputs but suggestions are welcome.

---

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

1 Files Affected:

• (modified) mlir/docs/Bufferization.md (+10-10)

diff --git a/mlir/docs/Bufferization.md b/mlir/docs/Bufferization.md
index d9d0751cae8c9dd..4e2d4a69e74587c 100644
--- a/mlir/docs/Bufferization.md
+++ b/mlir/docs/Bufferization.md
@@ -110,13 +110,13 @@ As an example, consider the following op: `%0 = tensor.insert %cst into
 %t[%idx] : tensor<?xf32>`
 
 `%t` is the destination in this example. When choosing a buffer for the result
-`%0`, One-Shot Bufferize considers only two options:
+`%0`, denoted as `buffer(%0)`, One-Shot Bufferize considers only two options:
 
-1.  buffer(`%0`) = buffer(`%t`).
-2.  buffer(`%0`) is a newly allocated buffer.
+1.  `buffer(%0) = buffer(%t)`, or
+2.  `buffer(%0)` is a newly allocated buffer.
 
 There may be other buffers in the same function that could potentially be used
-for buffer(`%0`), but those are not considered by One-Shot Bufferize to keep the
+for `buffer(%0)`, but those are not considered by One-Shot Bufferize to keep the
 bufferization simple. One-Shot Bufferize could be extended to consider such
 buffers in the future to achieve a better quality of bufferization.
 
@@ -131,10 +131,10 @@ memory allocation. E.g.:
 } : tensor<?xf32>
 ```
 
-The result of `tensor.generate` does not have a "destination", so bufferization
-allocates a new buffer. This could be avoided by choosing an op such as
-`linalg.generic`, which can express the same computation with a destination
-("out") tensor:
+The result of `tensor.generate` does not have a destination operand, so
+bufferization allocates a new buffer. This could be avoided by choosing an
+op such as `linalg.generic`, which can express the same computation with a
+destination operand, as specified behind outputs (`outs`):
 
 ```mlir
 #map = affine_map<(i) -> (i)>
@@ -165,7 +165,7 @@ such as a subsequent read of `%s`).
 
 RaW conflicts are detected with an analysis of SSA use-def chains (details
 later). One-Shot Bufferize works best if there is a single SSA use-def chain,
-where the result of a tensor op is the "destination" operand of the next tensor
+where the result of a tensor op is the destination operand of the next tensor
 ops, e.g.:
 
 ```mlir
@@ -263,7 +263,7 @@ must be inserted due to a RaW conflict. E.g.:
 }
 ```
 
-In the above example, a buffer copy of buffer(`%another_tensor`) (with `%cst`
+In the above example, a buffer copy of `buffer(%another_tensor)` (with `%cst`
 inserted) is yielded from the "then" branch.
 
 Note: Buffer allocations that are returned from a function are not deallocated.

[joker-eph]

Thanks for fixing the doc along the way! I wish everyone would do the same :)

[joker-eph]

I actually don't think this sentence is correct, but I should probably rewrite the entire first part of the doc separately.

[joker-eph]

The quote here are meant to express that this isn't really a "destination" at the SSA level but only an input for the operation.

[joker-eph]

Merging so that I can take another pass on it.

[joker-eph]

#70283