Merge f9d9aa4e83 into 51817951d0

Add docs for `#[collapse_debuginfo]` attribute

src/attributes.md

@@ -275,6 +275,7 @@ The following is an index of all built-in attributes.
     added in future.
 - Debugger
   - [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type.
+  - [`collapse_debuginfo`] — Controls how macro invocations are encoded in debuginfo.
 
 [Doc comments]: comments.md#doc-comments
 [ECMA-334]: https://www.ecma-international.org/publications-and-standards/standards/ecma-334/
@@ -293,6 +294,7 @@ The following is an index of all built-in attributes.
 [`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute
 [`cfg`]: conditional-compilation.md#the-cfg-attribute
 [`cold`]: attributes/codegen.md#the-cold-attribute
+[`collapse_debuginfo`]: attributes/debugger.md#the-collapse_debuginfo-attribute
 [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
 [`crate_type`]: linkage.md
 [`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute

src/attributes/debugger.md

@@ -139,3 +139,32 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil
 [Natvis documentation]: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects
 [pretty printing documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
+
+## The `collapse_debuginfo` attribute
+
+The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site,
+when generating debuginfo for code calling this macro.
+
+The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to macro definitions.
+
+Accepted options:
+- `#[collapse_debuginfo(yes)]` — code locations in debuginfo are collapsed.
+- `#[collapse_debuginfo(no)]` — code locations in debuginfo are not collapsed.
+- `#[collapse_debuginfo(external)]` — code locations in debuginfo are collapsed only if the macro comes from a different crate.
+
+The `external` behavior is the default for macros that don't have this attribute, unless they are built-in macros.
+For built-in macros the default is `yes`.
+
+> **Note**: `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes.
+
+```rust
+#[collapse_debuginfo(yes)]
+macro_rules! example {
+    () => {
+        println!("hello!");
+    };
+}
+```
+
+[attribute]: ../attributes.md
+[_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax

src/expressions.md

@@ -23,6 +23,7 @@
 >       | [_FieldExpression_]\
 >       | [_ClosureExpression_]\
 >       | [_AsyncBlockExpression_]\
+>       | [_ConstBlockExpression_]\
 >       | [_ContinueExpression_]\
 >       | [_BreakExpression_]\
 >       | [_RangeExpression_]\
@@ -311,6 +312,7 @@ They are never allowed before:
 [_ClosureExpression_]:            expressions/closure-expr.md
 [_ComparisonExpression_]:         expressions/operator-expr.md#comparison-operators
 [_CompoundAssignmentExpression_]: expressions/operator-expr.md#compound-assignment-expressions
+[_ConstBlockExpression_]:         expressions/block-expr.md#const-blocks
 [_ContinueExpression_]:           expressions/loop-expr.md#continue-expressions
 [_FieldExpression_]:              expressions/field-expr.md
 [_GroupedExpression_]:            expressions/grouped-expr.md

src/expressions/block-expr.md

@@ -117,6 +117,37 @@ loop {
 }
 ```
 
+## `const` blocks
+
+> **<sup>Syntax</sup>**\
+> _ConstBlockExpression_ :\
+> &nbsp;&nbsp; `const` _BlockExpression_
+
+A *const block* is a variant of a block expression which evaluates in the compile time instead of in the run time.
+
+A `const` block allows you to define a constant value without having to define a new `const` item, and thus is also sometimes called as inline `const` or anonymous `const`.
+
+For example, this code:
+
+```rust
+# fn foo(x: i32) -> i32 { x }
+fn main() {
+    let x = foo(const { 1 + 1 });
+}
+```
+
+is equivalent to:
+
+```rust
+# fn foo(x: i32) -> i32 { x }
+fn main() {
+    const FOO: i32 = 1 + 1;
+    let x = foo(FOO);
+}
+```
+
+A `const` block supports type inference so you do not have to write the type of the constant value like a `const` item. `const` blocks are allowed to reference general parameters in their scope.
+
 ## `unsafe` blocks
 
 > **<sup>Syntax</sup>**\