[Mlir-commits] [mlir] [mlir][Interfaces] Document completeness requirement of `RegionBranchOpInterface` (PR #202018)

[Matthias Springer]

https://github.com/matthias-springer updated https://github.com/llvm/llvm-project/pull/202018

>From 7ffada7f7ca9c843d5379a68e49769a73eeda4b8 Mon Sep 17 00:00:00 2001
From: Matthias Springer <me at m-sp.org>
Date: Tue, 9 Jun 2026 09:47:08 +0000
Subject: [PATCH] [mlir][Interfaces] Document completeness requirement of
 `RegionBranchOpInterface`

---
 .../mlir/Interfaces/ControlFlowInterfaces.td  | 39 +++++++++----------
 1 file changed, 19 insertions(+), 20 deletions(-)

diff --git a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
index 06fa724e05fab..a4c5cd4a8d5a2 100644
--- a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
+++ b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
@@ -118,15 +118,16 @@ def BranchOpInterface : OpInterface<"BranchOpInterface"> {
 def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
   let description = [{
     This interface provides information for region-holding operations that
-    exhibit branching behavior between held regions. I.e., this interface allows
-    for expressing control flow information for region holding operations.
+    exhibit branching behavior between held regions. It models the control flow
+    edges between regions (and between the op and its regions), as well as the
+    data flow (value propagation) that occurs along those control flow edges.
 
     This interface is meant to model well-defined cases of control-flow and
     value propagation, where what occurs along control-flow edges is assumed to
     be side-effect free.
 
-    A "region branch point" indicates a point from which a branch originates. It
-    can indicate:
+    A "region branch point" indicates the point from which a branch (edge)
+    originates. It can indicate:
     1. A `RegionBranchTerminatorOpInterface` terminator in any of the
        immediately nested regions of this op.
     2. `RegionBranchPoint::parent()`: the branch originates from outside of the
@@ -198,14 +199,13 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
       }]
     >,
     InterfaceMethod<[{
-        Returns the potential region successors when first executing the op.
+        Returns all potential region successors when first executing the op.
 
-        Unlike `getSuccessorRegions`, this method also passes along the
-        constant operands of this op. Based on these, the implementation may
-        filter out certain successors. By default, simply dispatches to
-        `getSuccessorRegions`. `operands` contains an entry for every
-        operand of this op, with a null attribute if the operand has no constant
-        value.
+        Unlike `getSuccessorRegions`, this method also receives the constant
+        operands of this op (one entry per operand, "null" if the operand has
+        no/unknown constant value). The implementation may use this information
+        to filter out successors. By default, it simply dispatches to
+        `getSuccessorRegions`.
 
         Note: The control flow does not necessarily have to enter any region of
         this op.
@@ -245,7 +245,7 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
            "::llvm::SmallVectorImpl<::mlir::RegionSuccessor> &":$regions)
     >,
     InterfaceMethod<[{
-        Returns the potential region successors when branching from any
+        Returns all potential region successors when branching from any
         terminator in `region`.
       }],
       "void", "getSuccessorRegions",
@@ -276,7 +276,7 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
         return ::mlir::ValueRange();
       }]>,
     InterfaceMethod<[{
-        Returns the potential branching points (predecessors) for a given
+        Returns all potential branching points (predecessors) for a given
         region successor.
       }],
       "void", "getPredecessors",
@@ -297,7 +297,7 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
         }
       }]>,
     InterfaceMethod<[{
-        Returns the potential values across all (predecessors) for a given successor
+        Returns all potential values across all (predecessors) for a given successor
         input, modeled by its index (its position in the list of values).
       }],
       "void", "getPredecessorValues",
@@ -439,14 +439,13 @@ def RegionBranchTerminatorOpInterface :
       }]
     >,
     InterfaceMethod<[{
-        Returns the potential region successors that are branched to after this
+        Returns all potential region successors that are branched to after this
         terminator based on the given constant operands.
 
-        This method also passes along the constant operands of this op.
-        `operands` contains an entry for every operand of this op, with a null
-        attribute if the operand has no constant value.
-
-        The default implementation simply dispatches to the parent
+        This method also receives the constant operands of this op (one entry
+        per operand, "null" if the operand has no/unknown constant value). The
+        implementation may use this information to filter out successors.
+        By default, it simply dispatches to the parent
         `RegionBranchOpInterface`'s `getSuccessorRegions` implementation.
       }],
       "void", "getSuccessorRegions",