[mlir][linalg][bufferize][NFC] Update comments in BufferizableOpInterface

Differential Revision: https://reviews.llvm.org/D116932

mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.h

@@ -426,8 +426,8 @@ private:
 void replaceOpWithBufferizedValues(RewriterBase &rewriter, Operation *op,
                                    ValueRange values);
 
-/// Replace an op with a new op. Tensor OpResults must be replaced with memref
-/// values.
+/// Replace an op with a new op. The new op must have the same number of
+/// results as the replaced op. The new op may not return any tensor values.
 template <typename OpTy, typename... Args>
 OpTy replaceOpWithNewBufferizedOp(RewriterBase &rewriter, Operation *op,
                                   Args &&...args) {

mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.td

@@ -195,13 +195,26 @@ def BufferizableOpInterface : OpInterface<"BufferizableOpInterface"> {
       InterfaceMethod<
         /*desc=*/[{
           Bufferize this op, i.e., rewrite it into a memref-based equivalent.
-          Tensor values should be mapped to buffer values using `state`.
+          Buffers of tensor SSA values can be retrieved via `state.getBuffer`.
+          Uses of tensor results of the existing tensor op can be replaced with
+          `replaceOpWithBufferizedValues` or `replaceOpWithNewBufferizedOp`.
+          These two functions automatically handle the tensor-to-memref type
+          conversion.
 
-          Implementations are required to required to bufferize nested ops
-          before returning. Otherwise, nested ops will not be bufferized.
+          The implementation of this method must be consistent with the
+          remaining methods, in particular `getAliasingOpOperand`. I.e., a
+          tensor result `r` may only be replaced with:
+          a) A buffer that aliases one of buffers in getAliasingOpOperand(r).
+          b) Or: A newly allocated buffer.
+
+          Regions of an op should be inlined into the new op instead of cloning
+          them. This is not only more efficient, but also necessary so that no
+          analysis results are lost. (Bufferization decisions are tracked via
+          OpOperand pointers and cloned ops have new OpOperands.) If regions are
+          cloned instead of inlined, additional buffer copies may be inserted.
 
           This method will never be called on ops that do not have at least one
-          tensor operand/result or a region.
+          tensor operand/result.
         }],
         /*retType=*/"LogicalResult",
         /*methodName=*/"bufferize",