custom MIR: add doc comment for debuginfo

library/core/src/intrinsics/mir.rs

@@ -249,6 +249,39 @@
 //!    `Call(ret_val = function(arg1, arg2, ...), ReturnTo(next_block), UnwindContinue())`.
 //!  - [`TailCall`] does not have a return destination or next block, so its syntax is just
 //!    `TailCall(function(arg1, arg2, ...))`.
+//!
+//! #### Debuginfo
+//!
+//! Debuginfo associates source code variable names (of variables that may not exist any more) with
+//! MIR expressions that indicate where the value of that variable is stored. The syntax to do so
+//! is:
+//! ```text
+//! debug source_var_name => expression;
+//! ```
+//! Both places and constants are supported in the `expression`.
+//!
+//! ```rust
+//! #![allow(internal_features)]
+//! #![feature(core_intrinsics, custom_mir)]
+//!
+//! use core::intrinsics::mir::*;
+//!
+//! #[custom_mir(dialect = "built")]
+//! fn debuginfo(arg: Option<&i32>) {
+//!     mir!(
+//!         // Debuginfo for a source variable `plain_local` that just duplicates `arg`.
+//!         debug plain_local => arg;
+//!         // Debuginfo for a source variable `projection` that can be computed by dereferencing
+//!         // a field of `arg`.
+//!         debug projection => *Field::<&i32>(Variant(arg, 1), 0);
+//!         // Debuginfo for a source variable `constant` that always holds the value `5`.
+//!         debug constant => 5_usize;
+//!         {
+//!             Return()
+//!         }
+//!     )
+//! }
+//! ```
 
 #![unstable(
     feature = "custom_mir",

tests/mir-opt/building/custom/debuginfo.constant.built.after.mir

@@ -0,0 +1,10 @@
+// MIR for `constant` after built
+
+fn constant() -> () {
+    debug scalar => const 5_usize;
+    let mut _0: ();
+
+    bb0: {
+        return;
+    }
+}

tests/mir-opt/building/custom/debuginfo.numbered.built.after.mir

@@ -2,7 +2,7 @@
 
 fn numbered(_1: (u32, i32)) -> () {
     debug first => (_1.0: u32);
-    debug second => (_1.0: u32);
+    debug second => (_1.1: i32);
     let mut _0: ();
 
     bb0: {

tests/mir-opt/building/custom/debuginfo.rs

@@ -1,4 +1,3 @@
-// skip-filecheck
 #![feature(custom_mir, core_intrinsics)]
 
 extern crate core;
@@ -7,6 +6,8 @@ use core::intrinsics::mir::*;
 // EMIT_MIR debuginfo.pointee.built.after.mir
 #[custom_mir(dialect = "built")]
 fn pointee(opt: &mut Option<i32>) {
+    // CHECK-LABEL: fn pointee(
+    // CHECK: debug foo => (((*_1) as variant#1).0: i32);
     mir! {
         debug foo => Field::<i32>(Variant(*opt, 1), 0);
         {
@@ -18,9 +19,12 @@ fn pointee(opt: &mut Option<i32>) {
 // EMIT_MIR debuginfo.numbered.built.after.mir
 #[custom_mir(dialect = "analysis", phase = "post-cleanup")]
 fn numbered(i: (u32, i32)) {
+    // CHECK-LABEL: fn numbered(
+    // CHECK: debug first => (_1.0: u32);
+    // CHECK: debug second => (_1.1: i32);
     mir! {
         debug first => i.0;
-        debug second => i.0;
+        debug second => i.1;
         {
             Return()
         }
@@ -34,6 +38,8 @@ struct S {
 // EMIT_MIR debuginfo.structured.built.after.mir
 #[custom_mir(dialect = "analysis", phase = "post-cleanup")]
 fn structured(i: S) {
+    // CHECK-LABEL: fn structured(
+    // CHECK: debug x => (_1.0: f32);
     mir! {
         debug x => i.x;
         {
@@ -45,6 +51,8 @@ fn structured(i: S) {
 // EMIT_MIR debuginfo.variant.built.after.mir
 #[custom_mir(dialect = "built")]
 fn variant(opt: Option<i32>) {
+    // CHECK-LABEL: fn variant(
+    // CHECK: debug inner => ((_1 as variant#1).0: i32);
     mir! {
         debug inner => Field::<i32>(Variant(opt, 1), 0);
         {
@@ -56,6 +64,9 @@ fn variant(opt: Option<i32>) {
 // EMIT_MIR debuginfo.variant_deref.built.after.mir
 #[custom_mir(dialect = "built")]
 fn variant_deref(opt: Option<&i32>) {
+    // CHECK-LABEL: fn variant_deref(
+    // CHECK: debug pointer => ((_1 as variant#1).0: &i32);
+    // CHECK: debug deref => (*((_1 as variant#1).0: &i32));
     mir! {
         debug pointer => Field::<&i32>(Variant(opt, 1), 0);
         debug deref => *Field::<&i32>(Variant(opt, 1), 0);
@@ -65,10 +76,24 @@ fn variant_deref(opt: Option<&i32>) {
     }
 }
 
+// EMIT_MIR debuginfo.constant.built.after.mir
+#[custom_mir(dialect = "built")]
+fn constant() {
+    // CHECK-LABEL: fn constant(
+    // CHECK: debug scalar => const 5_usize;
+    mir!(
+        debug scalar => 5_usize;
+        {
+            Return()
+        }
+    )
+}
+
 fn main() {
     numbered((5, 6));
     structured(S { x: 5. });
     variant(Some(5));
     variant_deref(Some(&5));
     pointee(&mut Some(5));
+    constant();
 }