[Mlir-commits] [mlir] [mlir][Interfaces][NFC] Better documentation for `RegionBranchOpInterface` (PR #66920)

[Markus Böck]

================
@@ -117,27 +117,58 @@ def BranchOpInterface : OpInterface<"BranchOpInterface"> {
 
 def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
   let description = [{
-    This interface provides information for region operations that contain
-    branching behavior between held regions, i.e. this interface allows for
+    This interface provides information for region operations that exhibit
+    branching behavior between held regions. I.e., this interface allows for
     expressing control flow information for region holding operations.
 
-    This interface is meant to model well-defined cases of control-flow of
+    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. For example, corresponding successor operands and
-    successor block arguments may have different types. In such cases,
-    `areTypesCompatible` can be implemented to compare types along control-flow
-    edges. By default, type equality is used.
+    be side-effect free.
+
+    A "region branch point" indicates a point from which a branch originates. It
+    can indicate either a region of this op or `RegionBranchPoint::parent()`. In
+    the latter case, the branch originates from outside of outside of the op,
+    i.e., when first executing this op.
+
+    A "region successor" indicates the target of a branch. It can indicate
+    either a region of this op or this op. In the former case, the region
+    successor is a region pointer and a range of block arguments to which the
+    "successor operands" are forwarded to. In the latter case, the control flow
+    leaves this op and the region successor is a range of results of this op to
+    which the successor operands are forwarded to.
----------------
zero9178 wrote:

Should this section maybe be on the constructors of `mlir::RegionSuccessor` as well? That class has been annoyingly underdocumented imo and I am super happy to see its behaviour spelled out. 

Personally speaking, the documentation of classes within C++ headers is also more accessible (at least in my workflow with the IDEs that I use) than the TableGen files, so having the documentation there is IMO preferrable. 

https://github.com/llvm/llvm-project/pull/66920