[llvm] [DebugInfo] Update policy for when to merge locations (PR #115349)

[Felipe de Azevedo Piovezan via llvm-commits]

================
@@ -76,9 +76,13 @@ When to merge instruction locations
 -----------------------------------
 
 A transformation should merge instruction locations if it replaces multiple
-instructions with a single merged instruction, *and* that merged instruction
-does not correspond to any of the original instructions' locations. The API to
-use is ``Instruction::applyMergedLocation``.
+instructions with one or more new instructions, *and* the new instruction(s)
+produce the output of more than one of the original instructions. The API to
+use is ``Instruction::applyMergedLocation``, and the new location should be a
+merge of the locations of all the instructions whose output is produced in the
+new instructions; typically, this includes any instruction being RAUWed by a new
+instruction, and excludes any instruction that only produces an intermediate
+value used by the RAUWed instruction.
----------------
felipepiovezan wrote:

>  with one or more new instructions

The new text is covering "new instructions" (plural!) but AFAICT we don't have an example of that in the text, which would help clarify something confusing in the text:

> The API to use is ``Instruction::applyMergedLocation``
> and the new location should be a merge of the locations
> of all the instructions whose output is produced in the
> new instructions

We talk about **the** location, but if we are in the plural case there would be possibly different merged locations, right?

I think a more precise wording is:

The API to use is ``Instruction::applyMergedLocation``. For each new instruction `I`, its new location should be a merge of the locations of all instructions whose output is produced by `I`.


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