Rollup merge of rust-lang#133625 - RalfJung:custom-mir-debug-info, r=compiler-errors

custom MIR: add doc comment for debuginfo

This is a revival of rust-lang#117015

Author: jieyouxu

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",