Revise text for inline and cold

Note in particular that `inline` and similar attributes can be applied
to `async` blocks as well as to closures.  Along with the editorial
revisions, let's say that and also discuss the current limitations
that affect how these can be applied.

Author: traviscross

src/attributes/codegen.md

@@ -3,11 +3,12 @@ r[attributes.codegen]
 
 The following [attributes] are used for controlling code generation.
 
+<!-- template:attributes -->
 r[attributes.codegen.inline]
 ### The `inline` attribute
 
 r[attributes.codegen.inline.intro]
-The *`inline` [attribute]* suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined.
+The *`inline` [attribute]* suggests whether a copy of the attributed function's code should be placed in the caller rather than generating a call to the function.
 
 > [!EXAMPLE]
 > ```rust
@@ -22,7 +23,7 @@ The *`inline` [attribute]* suggests that a copy of the attributed function shoul
 > ```
 
 > [!NOTE]
-> The `rustc` compiler automatically inlines functions based on internal heuristics. Incorrectly inlining functions can make the program slower, so this attribute should be used with care.
+> `rustc` automatically inlines functions when doing so seems worthwhile. Use this attribute carefully as poor decisions about what to inline can slow down programs.
 
 r[attributes.codegen.inline.syntax]
 The syntax for the `inline` attribute is:
@@ -35,44 +36,53 @@ The syntax for the `inline` attribute is:
 ```
 
 r[attributes.codegen.inline.allowed-positions]
-The `inline` attribute may only be used on:
+The `inline` attribute may only be applied to functions with [bodies] --- [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [trait impl], and associated functions in a [trait definition] when those functions have a [default definition] .
 
-- [Free functions][items.fn]
-- [Inherent associated functions][items.associated.fn]
-- [Trait impl functions][items.impl.trait]
-- [Trait definition functions][items.traits] with a body
-- [Closures][expr.closure]
+> [!NOTE]
+> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
 
 > [!NOTE]
-> `rustc` currently warns when `inline` is used in some other positions. This may become an error in the future.
+> Though the attribute can be applied to [closures] and [async blocks], the usefulness of this is limited as we do not yet support attributes on expressions.
+>
+> ```rust
+> // We allow attributes on statements.
+> #[inline] || (); // OK
+> #[inline] async {}; // OK
+> ```
+>
+> ```rust,compile_fail,E0658
+> // We don't yet allow attributes on expressions.
+> let f = #[inline] || (); // ERROR
+> ```
 
 r[attributes.codegen.inline.duplicates]
-Only the first instance of `inline` on an item is honored. Subsequent `inline` attributes are ignored.
+Only the first use of `inline` on a function has effect.
 
 > [!NOTE]
-> `rustc` currently warns on duplicate `inline` attributes. This may become an error in the future.
+> `rustc` lints against any use following the first. This may become an error in the future.
 
 r[attributes.codegen.inline.modes]
-There are three ways to use the inline attribute:
+The `inline` attribute supports these modes:
 
-* `#[inline]` *suggests* performing an inline expansion.
-* `#[inline(always)]` *suggests* that an inline expansion should always be performed.
-* `#[inline(never)]` *suggests* that an inline expansion should never be performed.
+- `#[inline]` *suggests* performing inline expansion.
+- `#[inline(always)]` *suggests* that inline expansion should always be performed.
+- `#[inline(never)]` *suggests* that inline expansion should never be performed.
 
 > [!NOTE]
-> `#[inline]` in every form is a hint, with no *requirements* on the language to place a copy of the attributed function in the caller.
+> In every form the attribute is a hint. The compiler may ignore it.
 
 r[attributes.codegen.inline.trait]
-When `inline` is applied to a function in a [trait definition], it applies only to that function when used as a default function for a trait implementation and not to all trait implementations.
+When `inline` is applied to a function in a [trait], it applies only to the code of the [default definition].
 
 r[attributes.codegen.inline.externally-exported]
-The `inline` attribute is ignored if the function is externally exported. This may happen with the [`no_mangle`] or [`export_name`] attribute.
+The `inline` attribute is ignored if the function is externally exported with [`no_mangle`] or [`export_name`].
 
+<!-- template:attributes -->
 r[attributes.codegen.cold]
 ### The `cold` attribute
 
 r[attributes.codegen.cold.intro]
-The *`cold` [attribute]* suggests that the attributed function is unlikely to be called.
+The *`cold` [attribute]* suggests that the attributed function is unlikely to be called which may help the compiler produce better code.
 
 > [!EXAMPLE]
 > ```rust
@@ -81,31 +91,27 @@ The *`cold` [attribute]* suggests that the attributed function is unlikely to be
 > ```
 
 r[attributes.codegen.cold.syntax]
-The `cold` attribute uses the [MetaWord] syntax and thus does not take any inputs.
+The `cold` attribute uses the [MetaWord] syntax.
 
 r[attributes.codegen.cold.allowed-positions]
-The `cold` attribute may only be used on:
+The `cold` attribute may only be applied to functions with [bodies] --- [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [trait impl], and associated functions in a [trait definition] when those functions have a [default definition] .
 
-- [Free functions][items.fn]
-- [Inherent associated functions][items.associated.fn]
-- [Trait impl functions][items.impl.trait]
-- [Trait definition functions][items.traits] with a body
-- [External block functions][items.extern.fn]
-- [Closures][expr.closure]
+> [!NOTE]
+> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
 
 > [!NOTE]
-> `rustc` currently warns when `inline` is used in some other positions. This may become an error in the future.
+> Though the attribute can be applied to [closures] and [async blocks], the usefulness of this is limited as we do not yet support attributes on expressions.
 
 <!-- TODO: rustc currently seems to allow cold on a trait function without a body, but it appears to be ignored. I think that may be a bug, and it should at least warn if not reject (like inline does). -->
 
 r[attributes.codegen.cold.duplicates]
-Duplicate instances of the `cold` attribute are ignored.
+Only the first use of `cold` on a function has effect.
 
 > [!NOTE]
-> `rustc` currently warns on duplicate `cold` attributes.
+> `rustc` lints against any use following the first. This may become an error in the future.
 
 r[attributes.codegen.cold.trait]
-When `cold` is applied to a function in a [trait definition], it applies only to that function when used as a default function for a trait implementation and not to all trait implementations.
+When `cold` is applied to a function in a [trait], it applies only to the code of the [default definition].
 
 r[attributes.codegen.naked]
 ## The `naked` attribute
@@ -716,11 +722,14 @@ r[attributes.codegen.instruction_set.syntax]
 The `instruction_set` attribute uses the [MetaListPaths] syntax to specify a single path consisting of the architecture family name and instruction set name.
 
 r[attributes.codegen.instruction_set.allowed-positions]
-The `instruction_set` attribute may only be applied to functions, including [closures][expr.closure], [free functions][items.fn], and associated functions defined (i.e. with a body) in [inherent impls][items.associated.fn], [trait impls][items.impl.trait], and [trait definitions][items.traits].
+The `instruction_set` attribute may only be applied to functions with [bodies] --- [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [trait impl], and associated functions in a [trait definition] when those functions have a [default definition] .
 
 > [!NOTE]
 > `rustc` ignores use in other positions but lints against it. This may become an error in the future.
 
+> [!NOTE]
+> Though the attribute can be applied to [closures] and [async blocks], the usefulness of this is limited as we do not yet support attributes on expressions.
+
 r[attributes.codegen.instruction_set.duplicates]
 The `instruction_set` attribute may be used only once on a function.
 
@@ -745,21 +754,29 @@ If the address of the function is taken as a function pointer, the low bit of th
 
 [`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu
 [`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature
-[`export_name`]: ../abi.md#the-export_name-attribute
+[`export_name`]: abi.export_name
 [`is_aarch64_feature_detected`]: ../../std/arch/macro.is_aarch64_feature_detected.html
 [`is_x86_feature_detected`]: ../../std/arch/macro.is_x86_feature_detected.html
 [`Location`]: core::panic::Location
 [`naked_asm!`]: ../inline-assembly.md
-[`no_mangle`]: ../abi.md#the-no_mangle-attribute
+[`no_mangle`]: abi.no_mangle
 [`target_feature` conditional compilation option]: ../conditional-compilation.md#target_feature
 [`unused_variables`]: ../../rustc/lints/listing/warn-by-default.html#unused-variables
+[associated functions]: items.associated.fn
+[async blocks]: expr.block.async
 [attribute]: ../attributes.md
 [attributes]: ../attributes.md
+[bodies]: items.fn.body
+[closures]: expr.closure
+[default definition]: items.traits.associated-item-decls
+[free functions]: items.fn
 [function body]: ../items/functions.md#function-body
 [functions]: ../items/functions.md
+[inherent impl]: items.impl.inherent
 [rust-abi]: ../items/external-blocks.md#abi
 [target architecture]: ../conditional-compilation.md#target_arch
-[trait]: ../items/traits.md
-[trait definition]: ../items/traits.md
+[trait]: items.traits
+[trait definition]: items.traits
+[trait impl]: items.impl.trait
 [undefined behavior]: ../behavior-considered-undefined.md
 [unsafe attribute]: ../attributes.md#r-attributes.safety