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

[Jeremy Morse via llvm-commits]

https://github.com/jmorse created https://github.com/llvm/llvm-project/pull/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!

>From 334de5002ed08b05a2a200950a39132071c93b5d Mon Sep 17 00:00:00 2001
From: Jeremy Morse <jeremy.morse at sony.com>
Date: Tue, 28 Jan 2025 10:30:18 +0000
Subject: [PATCH] [Docs][DebugInfo] Summarise what people need to do for
 RemoveDIs now

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!
---
 llvm/docs/RemoveDIsDebugInfo.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

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