[llvm] [Docs] Update debug info transformation guidance (PR #216217)

[Stephen Tozer via llvm-commits]

================
@@ -298,73 +296,59 @@ immediately used by debug value records everywhere possible.
 For example, here is a module before:
 
 ```llvm
-define void @f(i32* %x) {
+define void @f(ptr %x) {
 entry:
-  %x.addr = alloca i32*, align 8
-  store i32* %x, i32** %x.addr, align 8
-  %0 = load i32*, i32** %x.addr, align 8
-  store i32 10, i32* %0, align 4
+  %x.addr = alloca ptr, align 8
+  store ptr %x, ptr %x.addr, align 8
+  %0 = load ptr, ptr %x.addr, align 8
+  store i32 10, ptr %0, align 4
   ret void
 }
 ```
 
-and after running `opt -debugify`:
+and the function body after running
+`opt -passes=debugify -S -o - debugify-sample.ll`:
 
 ```llvm
-define void @f(i32* %x) !dbg !6 {
+define void @f(ptr %x) !dbg !5 {
 entry:
-  %x.addr = alloca i32*, align 8, !dbg !12
-    #dbg_value(i32** %x.addr, !9, !DIExpression(), !12)
-  store i32* %x, i32** %x.addr, align 8, !dbg !13
-  %0 = load i32*, i32** %x.addr, align 8, !dbg !14
-    #dbg_value(i32* %0, !11, !DIExpression(), !14)
-  store i32 10, i32* %0, align 4, !dbg !15
+  %x.addr = alloca ptr, align 8, !dbg !12
+    #dbg_value(ptr %x.addr, !9, !DIExpression(), !12)
+  store ptr %x, ptr %x.addr, align 8, !dbg !13
+  %0 = load ptr, ptr %x.addr, align 8, !dbg !14
+    #dbg_value(ptr %0, !11, !DIExpression(), !14)
+  store i32 10, ptr %0, align 4, !dbg !15
   ret void, !dbg !16
 }
-
-!llvm.dbg.cu = !{!0}
-!llvm.debugify = !{!3, !4}
-!llvm.module.flags = !{!5}
-
-!0 = distinct !DICompileUnit(language: DW_LANG_C, file: !1, producer: "debugify", isOptimized: true, runtimeVersion: 0, emissionKind: FullDebug, enums: !2)
-!1 = !DIFile(filename: "debugify-sample.ll", directory: "/")
-!2 = !{}
-!3 = !{i32 5}
-!4 = !{i32 2}
-!5 = !{i32 2, !"Debug Info Version", i32 3}
-!6 = distinct !DISubprogram(name: "f", linkageName: "f", scope: null, file: !1, line: 1, type: !7, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: true, unit: !0, retainedNodes: !8)
-!7 = !DISubroutineType(types: !2)
-!8 = !{!9, !11}
-!9 = !DILocalVariable(name: "1", scope: !6, file: !1, line: 1, type: !10)
-!10 = !DIBasicType(name: "ty64", size: 64, encoding: DW_ATE_unsigned)
-!11 = !DILocalVariable(name: "2", scope: !6, file: !1, line: 3, type: !10)
-!12 = !DILocation(line: 1, column: 1, scope: !6)
-!13 = !DILocation(line: 2, column: 1, scope: !6)
-!14 = !DILocation(line: 3, column: 1, scope: !6)
-!15 = !DILocation(line: 4, column: 1, scope: !6)
-!16 = !DILocation(line: 5, column: 1, scope: !6)
 ```
 
 #### Using `debugify`
 
 A simple way to use `debugify` is as follows:
 
 ```bash
-$ opt -debugify -pass-to-test -check-debugify sample.ll
+$ opt -passes=debugify,pass-to-test,check-debugify -disable-output sample.ll
 ```
 
-This will inject synthetic DI to `sample.ll` run the `pass-to-test` and
-then check for missing DI. The `-check-debugify` step can of course be
-omitted in favor of more customizable FileCheck directives.
+Replace `pass-to-test` with the pipeline to test. This adds synthetic locations
+and variables to `sample.ll`, runs the pipeline, and reports anything missing
+as a warning. `check-debugify` still prints `PASS` and `opt` exits successfully,
+so use FileCheck to make a warning fail the test:
----------------
SLTozer wrote:

Think this requires maybe a bit more explanation - it's not a regression on the original explanation but it needs more context imo, e.g. "This can be used for writing tests that check that debug info is preserved through one or more passes, using FileCheck to verify check-debugify's output.`, before explaining the details of how to do so. Also, `check-debugify` _can_ print `FAIL`, and it may be useful to write something like `CHECK-NOT: CheckModuleDebugify: FAIL` for some cases; it might be that the new text would be better expressed as "In some cases when debug info is not preserved, `check-debugify` will log these cases with `WARNING: ...`, and will still print `PASS`, so..."

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