[MLIR] Clarify createOrFold() doc as opportunistic eager folding (llvm#160565)

This addresses user confusion about createOrFold behavior compared to
canonicalization passes, as discussed in llvm#159844.

---------

Co-authored-by: Mehdi Amini <[email protected]>

Author: swote-git

mlir/include/mlir/IR/Builders.h

@@ -515,6 +515,12 @@ class OpBuilder : public Builder {
   /// Create an operation of specific op type at the current insertion point,
   /// and immediately try to fold it. This functions populates 'results' with
   /// the results of the operation.
+  ///
+  /// Note: This performs opportunistic eager folding during IR construction.
+  /// The folders are designed to operate efficiently on canonical IR, which 
+  /// this API does not enforce. Complete folding isn't only expected in the
+  /// context of canonicalization which intertwine folders with pattern 
+  /// rewrites until fixed-point.
   template <typename OpTy, typename... Args>
   void createOrFold(SmallVectorImpl<Value> &results, Location location,
                     Args &&...args) {