[llvm] a83ec0f - [Utils] Improve documentation for `cloneLoopWithPreheader()` (#208817)

[via llvm-commits]

Author: Congzhe Cao
Date: 2026-07-10T23:48:11-04:00
New Revision: a83ec0fb845e04b1b579decc4cc8f56245267c16

URL: https://github.com/llvm/llvm-project/commit/a83ec0fb845e04b1b579decc4cc8f56245267c16
DIFF: https://github.com/llvm/llvm-project/commit/a83ec0fb845e04b1b579decc4cc8f56245267c16.diff

LOG: [Utils] Improve documentation for `cloneLoopWithPreheader()` (#208817)

Fixed #191471.

The client needs to further update the CFG and DominatorTree after
calling `cloneLoopWithPreheader()` to ensure the IR remains valid, 
the function itself does not automatically update the control flow fully.
Clarified and improved the comments for the function.

Added: 
    

Modified: 
    llvm/include/llvm/Transforms/Utils/Cloning.h
    llvm/lib/Transforms/Utils/CloneFunction.cpp

Removed: 
    


################################################################################
diff  --git a/llvm/include/llvm/Transforms/Utils/Cloning.h b/llvm/include/llvm/Transforms/Utils/Cloning.h
index 6b9aced467704..354210ce3695f 100644
--- a/llvm/include/llvm/Transforms/Utils/Cloning.h
+++ b/llvm/include/llvm/Transforms/Utils/Cloning.h
@@ -370,6 +370,8 @@ LLVM_ABI InlineResult InlineFunction(CallBase &CB, InlineFunctionInfo &IFI,
 ///
 /// Updates LoopInfo and DominatorTree assuming the loop is dominated by block
 /// \p LoopDomBB.  Insert the new blocks before block specified in \p Before.
+/// The client needs to further update the CFG and DominatorTree after calling
+/// this function, to ensure the IR remains valid.
 /// Note: Only innermost loops are supported.
 LLVM_ABI Loop *cloneLoopWithPreheader(BasicBlock *Before, BasicBlock *LoopDomBB,
                                       Loop *OrigLoop, ValueToValueMapTy &VMap,

diff  --git a/llvm/lib/Transforms/Utils/CloneFunction.cpp b/llvm/lib/Transforms/Utils/CloneFunction.cpp
index 35de43f14bb23..7896b78a2c208 100644
--- a/llvm/lib/Transforms/Utils/CloneFunction.cpp
+++ b/llvm/lib/Transforms/Utils/CloneFunction.cpp
@@ -1021,6 +1021,8 @@ void llvm::remapInstructionsInBlocks(ArrayRef<BasicBlock *> Blocks,
 ///
 /// Updates LoopInfo and DominatorTree assuming the loop is dominated by block
 /// \p LoopDomBB.  Insert the new blocks before block specified in \p Before.
+/// The client needs to further update the CFG and DominatorTree after calling
+/// this function, to ensure the IR remains valid.
 Loop *llvm::cloneLoopWithPreheader(BasicBlock *Before, BasicBlock *LoopDomBB,
                                    Loop *OrigLoop, ValueToValueMapTy &VMap,
                                    const Twine &NameSuffix, LoopInfo *LI,