[llvm] 65f81df - [Docs][DebugInfo] Summarise what people need to do for RemoveDIs now (#124725)

[via llvm-commits]

Author: Jeremy Morse
Date: 2025-01-28T11:31:15Z
New Revision: 65f81df473904d2df2b9eaa91ff4fcbe69f8fb00

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

LOG: [Docs][DebugInfo] Summarise what people need to do for RemoveDIs now (#124725)

Replace the "what I need to do" section of the RemoveDIs docs with a
paragraph about preserving start-of-block iterators. Hopefully this is
concise enough to remain in peoples heads going forwards!

Added: 
    

Modified: 
    llvm/docs/RemoveDIsDebugInfo.md

Removed: 
    


################################################################################
diff  --git a/llvm/docs/RemoveDIsDebugInfo.md b/llvm/docs/RemoveDIsDebugInfo.md
index c9012548f7578e..db22d1df758fa5 100644
--- a/llvm/docs/RemoveDIsDebugInfo.md
+++ b/llvm/docs/RemoveDIsDebugInfo.md
@@ -24,7 +24,13 @@ The debug records are not instructions, do not appear in the instruction list, a
 
 # Great, what do I need to do!
 
-Very little -- we've already instrumented all of LLVM to handle these new records ("`DbgRecords`") and behave identically to past LLVM behaviour. This is currently being turned on by default, so that `DbgRecords` will be used by default in memory, IR, and bitcode.
+We've largely completed the migration. The remaining rough edge is that going forwards, instructions must be inserted into basic blocks using iterators rather than instruction pointers. In almost all circumstances you can just call `getIterator` on an instruction pointer -- however, if you call a function that returns the start of a basic block, such as:
+
+1. BasicBlock::begin
+2. BasicBlock::getFirstNonPHIIt
+3. BasicBlock::getFirstInsertionPt
+
+Then you must past that iterator into the insertion function without modification (the iterator carries a debug-info bit). That's all! Read on for a more detailed explanation.
 
 ## API Changes