[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
----------------
felipepiovezan wrote:

Probably a case where repetition is preferred to avoid any ambiguity: 
"optional replacement for :ref:`debug intrinsics<dbg_intrinsics>`,; debug records will be output..."

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