[llvm] [RemoveDIs] Add documentation for IR debug records (PR #81156)

[Felipe de Azevedo Piovezan via llvm-commits]

================
@@ -12664,6 +12668,29 @@ Example:
 
       %tok = cleanuppad within %cs []
 
+.. _debugrecords:
+
+Debug Records
+-----------------------
+
+Debug records appear interleaved with instructions, but are not instructions;
+they are used only to define debug information, and have no effect on generated
+code. They are distinguished from instructions by the use of a leading `#` and
+an extra level of indentation. As an example:
+
+.. code-block:: llvm
+
+  %inst1 = op1 %a, %b
+    #dbg_value(%inst1, !10, !DIExpression(), !11)
+  %inst2 = op2 %inst1, %c
+
+These debug records are an optional replacement for
+:ref:`debug intrinsics<dbg_intrinsics>`, which will be output if the
+``--write-experimental-debuginfo`` flag is passed to LLVM; it is an error for both
+records and intrinsics to appear in the same module. More information about the
+meaning of debug records can be found in the `LLVM Source Level Debugging
----------------
felipepiovezan wrote:

brevity: ~~the meaning of~~

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