refine mir debuginfo docs

Author: RalfJung

core/src/intrinsics/mir.rs

@@ -252,8 +252,13 @@
 //!
 //! #### Debuginfo
 //!
-//!  - A debuginfo name can be given to a local using `debug my_name => contents;`.
-//!    For `contents`, we use the same syntax as operands, to support both places and constants.
+//! 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)]
@@ -262,10 +267,14 @@
 //! use core::intrinsics::mir::*;
 //!
 //! #[custom_mir(dialect = "built")]
-//! fn debuginfo(option: Option<&i32>) {
+//! fn debuginfo(arg: Option<&i32>) {
 //!     mir!(
-//!         debug option => option;
-//!         debug projection => *Field::<&i32>(Variant(option, 1), 0);
+//!         // 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()