From 0686253ece3ab7f0e4ce726a8c9784f36803115f Mon Sep 17 00:00:00 2001
From: Luca Versari <veluca93@gmail.com>
Date: Mon, 1 Jun 2026 21:34:14 +0200
Subject: [PATCH 01/11] Stabilize #[optimize] attribute.

---
 src/attributes.md         |  2 ++
 src/attributes/codegen.md | 50 +++++++++++++++++++++++++++++++++++++++
 src/items/functions.md    |  2 ++
 3 files changed, 54 insertions(+)

diff --git a/src/attributes.md b/src/attributes.md
index 7b405a143c..45fbbc534f 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -255,6 +255,7 @@ The following is an index of all built-in attributes.
   - [`cold`] --- Hint that a function is unlikely to be called.
   - [`naked`] --- Prevent the compiler from emitting a function prologue and epilogue.
   - [`no_builtins`] --- Disables use of certain built-in functions.
+  - [`optimize`] --- Controls the level of optimization to be applied to the function.
   - [`target_feature`] --- Configure platform-specific code generation.
   - [`track_caller`] --- Pass the parent call location to `std::panic::Location::caller()`.
   - [`instruction_set`] --- Specify the instruction set used to generate a function's code.
@@ -328,6 +329,7 @@ The following is an index of all built-in attributes.
 [`no_mangle`]: abi.md#the-no_mangle-attribute
 [`no_std`]: names/preludes.md#the-no_std-attribute
 [`non_exhaustive`]: attributes/type_system.md#the-non_exhaustive-attribute
+[`optimize`]: attributes/codegen.md#the-optimize-attribute
 [`panic_handler`]: panic.md#the-panic_handler-attribute
 [`path`]: items/modules.md#the-path-attribute
 [`proc_macro_attribute`]: procedural-macros.md#the-proc_macro_attribute-attribute
diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 696e1dcd5d..0590621eac 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -235,6 +235,56 @@ Only the first use of the `no_builtins` attribute has effect.
 > [!NOTE]
 > `rustc` lints against any use following the first.
 
+<!-- template:attributes -->
+r[attributes.codegen.optimize]
+## The `optimize` attribute
+
+r[attributes.codegen.optimize.intro]
+The *`optimize` [attribute]* suggests whether a function, inherent method, trait method, or closure should be optimized for size or speed.
+
+This attribute has no effect if optimizations are disabled (i.e. `opt-level` is `0`).
+
+> [!EXAMPLE]
+> ```rust
+> #[optimize(size)]
+> pub fn example1() {}
+>
+> #[optimize(speed)]
+> pub fn example2() {}
+>
+> #[optimize(none)]
+> pub fn example3() {}
+> ```
+
+r[attributes.codegen.optimize.syntax]
+The syntax for the `optimize` attribute is:
+
+```grammar,attributes
+@root OptimizeAttribute ->
+      `optimize` `(` `size` `)`
+    | `optimize` `(` `speed` `)`
+    | `optimize` `(` `none` `)`
+```
+
+r[attributes.codegen.optimize.allowed-positions]
+The `optimize` attribute may only be applied to [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [trait impl], and associated functions in a [trait definition].
+
+r[attributes.codegen.optimize.closures]
+Unless overridden, [closures] inherit the `optimize` attribute of the enclosing function.
+
+r[attributes.codegen.optimize.duplicates]
+Applying multiple `optimize` attributes to the same function is an error.
+
+r[attributes.codegen.optimize.modes]
+The `optimize` attribute supports these modes:
+
+- `#[optimize(size)]` suggests prioritizing minimizing code size, potentially at the cost of execution performance.
+- `#[optimize(speed)]` suggests prioritizing execution performance, potentially at the cost of code size.
+- `#[optimize(none)]` suggests not optimizing the function, with similar effects to applying -Copt-level=0 locally.
+
+> [!NOTE]
+> In every form the attribute is a hint. The compiler may ignore it.
+
 r[attributes.codegen.target_feature]
 ## The `target_feature` attribute
 
diff --git a/src/items/functions.md b/src/items/functions.md
index 25ae723a20..db10195793 100644
--- a/src/items/functions.md
+++ b/src/items/functions.md
@@ -707,6 +707,7 @@ The attributes that have meaning on a function are:
 - [`link_section`]
 - [`must_use`]
 - [`no_mangle`]
+- [`optimize`]
 - [Lint check attributes]
 - [Procedural macro attributes]
 - [Testing attributes]
@@ -764,6 +765,7 @@ fn foo_oof(#[some_inert_attribute] arg: u8) {
 [`export_name`]: ../abi.md#the-export_name-attribute
 [`link_section`]: ../abi.md#the-link_section-attribute
 [`no_mangle`]: ../abi.md#the-no_mangle-attribute
+[`optimize`]: ../attributes/codegen.md#the-optimize-attribute
 [built-in attributes]: ../attributes.md#built-in-attributes-index
 [trait item]: traits.md
 [method]: associated-items.md#methods

From f1a6cbdb66bb014a78d8b7f436fcc0dc1f56b34e Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Tue, 29 Sep 2026 20:50:25 +0000
Subject: [PATCH 02/11] Restore review fixes lost from the `optimize` section

An earlier update of this branch lost some changes that had been made
in response to the review by Eric Huss.  Let's restore those and also
adjust the wording of the duplicates rule to follow the template.
---
 src/attributes/codegen.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 0590621eac..34e8a2c4ba 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -240,7 +240,7 @@ r[attributes.codegen.optimize]
 ## The `optimize` attribute
 
 r[attributes.codegen.optimize.intro]
-The *`optimize` [attribute]* suggests whether a function, inherent method, trait method, or closure should be optimized for size or speed.
+The *`optimize` [attribute]* suggests an optimization goal for the attributed function: size, speed, or none.
 
 This attribute has no effect if optimizations are disabled (i.e. `opt-level` is `0`).
 
@@ -267,13 +267,13 @@ The syntax for the `optimize` attribute is:
 ```
 
 r[attributes.codegen.optimize.allowed-positions]
-The `optimize` attribute may only be applied to [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [trait impl], and associated functions in a [trait definition].
+The `optimize` 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].
 
 r[attributes.codegen.optimize.closures]
 Unless overridden, [closures] inherit the `optimize` attribute of the enclosing function.
 
 r[attributes.codegen.optimize.duplicates]
-Applying multiple `optimize` attributes to the same function is an error.
+The `optimize` attribute may be used only once on a function.
 
 r[attributes.codegen.optimize.modes]
 The `optimize` attribute supports these modes:

From c253dd2dbda3453552c0b0d3e47d84d8ac59158f Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Tue, 29 Sep 2026 20:50:25 +0000
Subject: [PATCH 03/11] Reword the `optimize` modes

The earlier wording, that `optimize(none)` "suggests not optimizing
the function", could be read to suggest that it's asking specifically
for optimizations *not* to happen rather than *not* asking for
optimizations to happen.  This would arguably be a tier below
`-Copt-level=0`.

In the lang call on 2026-07-29, the meeting consensus was that with
`optimize(none)` we're not asking for optimizations to happen rather
than asking for optimizations to not happen.[^1]

Let's adopt this framing here.

[^1]: https://github.com/rust-lang/rust/pull/157273#issuecomment-5120621919
---
 src/attributes/codegen.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 34e8a2c4ba..8a630bb088 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -278,13 +278,21 @@ The `optimize` attribute may be used only once on a function.
 r[attributes.codegen.optimize.modes]
 The `optimize` attribute supports these modes:
 
-- `#[optimize(size)]` suggests prioritizing minimizing code size, potentially at the cost of execution performance.
-- `#[optimize(speed)]` suggests prioritizing execution performance, potentially at the cost of code size.
-- `#[optimize(none)]` suggests not optimizing the function, with similar effects to applying -Copt-level=0 locally.
+- `#[optimize(size)]` suggests optimizing for smaller code, even at the cost of execution speed.
+- `#[optimize(speed)]` suggests optimizing for faster execution, even at the cost of code size.
+- `#[optimize(none)]` suggests compiling the function as though no optimization had been requested for it, whatever was requested for the crate as a whole.
 
 > [!NOTE]
 > In every form the attribute is a hint. The compiler may ignore it.
 
+> [!WARNING]
+> `#[optimize(none)]` does not make the function opaque to the optimizer. In addition to ignoring the attribute, the compiler may still optimize the function's callers using what it knows about the function and may still change the function itself in other ways, so the attribute cannot be relied on to keep a computation from being optimized away.
+
+> [!NOTE]
+> `rustc` currently optimizes a function with `#[optimize(none)]` much as it would at `-C opt-level=0`, regardless of the crate's optimization level, and does not inline it into its callers.
+>
+> Settings that base their defaults on the optimization level, such as debug assertions and overflow checks, ignore this attribute and use the crate's optimization level.
+
 r[attributes.codegen.target_feature]
 ## The `target_feature` attribute
 

From 3bdbd6e51b29eec3a87ed4092da8d6c547407f7e Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Tue, 29 Sep 2026 20:50:25 +0000
Subject: [PATCH 04/11] Say which bodies inherit the `optimize` attribute

We need to say explicitly how the inheritance works for this
attribute; we need to define the behavior for `async` blocks as well
as for closures; and we need to address `const` blocks.  Let's do
those things.
---
 src/attributes/codegen.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 8a630bb088..17758a5a40 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -269,9 +269,6 @@ The syntax for the `optimize` attribute is:
 r[attributes.codegen.optimize.allowed-positions]
 The `optimize` 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].
 
-r[attributes.codegen.optimize.closures]
-Unless overridden, [closures] inherit the `optimize` attribute of the enclosing function.
-
 r[attributes.codegen.optimize.duplicates]
 The `optimize` attribute may be used only once on a function.
 
@@ -293,6 +290,24 @@ The `optimize` attribute supports these modes:
 >
 > Settings that base their defaults on the optimization level, such as debug assertions and overflow checks, ignore this attribute and use the crate's optimization level.
 
+r[attributes.codegen.optimize.closures]
+Closures and [async blocks] without an `optimize` attribute of their own inherit the attribute in effect on the innermost enclosing function, closure, or async block, which may itself be one inherited rather than one written directly. The body of an [async function] inherits the attribute in effect on the function, and the body of an [async closure] inherits the attribute in effect on the closure. Items and [const blocks] within a function do not inherit the attribute in effect on the function, nor do the closures and async blocks within them.
+
+```rust
+#[optimize(none)]
+pub fn f() {
+    // This closure has no `optimize` attribute of its own, so its
+    // body inherits `optimize(none)` from `f`.
+    let c = || 1 + 2;
+    c();
+}
+
+#[optimize(size)]
+pub async fn g() {
+    // This body inherits `optimize(size)` from `g`.
+}
+```
+
 r[attributes.codegen.target_feature]
 ## The `target_feature` attribute
 
@@ -986,6 +1001,7 @@ If the address of the function is taken as a function pointer, the low bit of th
 [attributes]: ../attributes.md
 [bodies]: items.fn.body
 [closures]: expr.closure
+[const blocks]: expr.block.const
 [default definition]: items.traits.associated-item-decls
 [free functions]: items.fn
 [function body]: items.fn.body

From a76e530ad840f286acb4d56bf94503b96d7c0a90 Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Tue, 29 Sep 2026 20:50:25 +0000
Subject: [PATCH 05/11] Add a trait rule for the `optimize` attribute

As with `cold` and `inline`, putting the `optimize` attribute on an
associated function within a trait definition only applies the effect
of that attribute to the body within the trait definition, not to the
bodies of function definitions within implementations of the trait.
Let's say that.
---
 src/attributes/codegen.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 17758a5a40..564b922882 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -308,6 +308,24 @@ pub async fn g() {
 }
 ```
 
+r[attributes.codegen.optimize.trait]
+When `optimize` is applied to a function in a [trait], it applies only to the code of the [default definition].
+
+```rust
+pub trait Tr {
+    // The default definition is optimized for size.
+    #[optimize(size)]
+    fn f(&self) {}
+}
+
+pub struct S;
+impl Tr for S {
+    // This implementation of `Tr::f` does not inherit the trait's
+    // `optimize(size)`; it uses the crate's optimization level.
+    fn f(&self) {}
+}
+```
+
 r[attributes.codegen.target_feature]
 ## The `target_feature` attribute
 

From 1b9ca8bbe9a6228a076a5ffbcb587dd1c86fc1f7 Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Tue, 29 Sep 2026 20:50:25 +0000
Subject: [PATCH 06/11] Document that `optimize(none)` conflicts with `inline`

It's an error to write `optimize(none)` and `inline` or
`inline(always)` on the same function, though it's OK for the effect
of `optimize(none)` to be inherited on a closure that is marked with
`inline` or `inline(always)`.  Let's make these things clear.
---
 src/attributes/codegen.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 564b922882..3503969fbd 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -84,6 +84,25 @@ When `inline` is applied to an [async function] or [async closure], it applies o
 r[attributes.codegen.inline.externally-exported]
 The `inline` attribute is ignored if the function is externally exported with [`no_mangle`] or [`export_name`].
 
+r[attributes.codegen.inline.optimize]
+`#[inline]` and `#[inline(always)]` may not be used with `#[optimize(none)]` on the same function. (See [attributes.codegen.optimize.inline].)
+
+```rust,compile_fail
+#[optimize(none)]
+#[inline] // ERROR: Not allowed.
+fn f() {}
+```
+
+`#[inline]` and `#[inline(always)]` may still be used on a closure or async block that inherits `optimize(none)`. (See [attributes.codegen.optimize.closures].)
+
+```rust
+#[optimize(none)]
+pub fn f() {
+    #[inline] || (); // Inherits `optimize(none)`.
+    #[inline(always)] async {}; // Inherits `optimize(none)`.
+}
+```
+
 <!-- template:attributes -->
 r[attributes.codegen.cold]
 ### The `cold` attribute
@@ -290,6 +309,25 @@ The `optimize` attribute supports these modes:
 >
 > Settings that base their defaults on the optimization level, such as debug assertions and overflow checks, ignore this attribute and use the crate's optimization level.
 
+r[attributes.codegen.optimize.inline]
+`#[optimize(none)]` may not be used with `#[inline]` or `#[inline(always)]` on the same function. It may be used with `#[inline(never)]`. (See [attributes.codegen.inline.optimize].)
+
+```rust,compile_fail
+#[optimize(none)]
+#[inline] // ERROR: Not allowed.
+fn f() {}
+```
+
+A closure or async block that inherits `optimize(none)` may still be marked with `#[inline]` or `#[inline(always)]`. (See [attributes.codegen.optimize.closures].)
+
+```rust
+#[optimize(none)]
+pub fn f() {
+    #[inline] || (); // Inherits `optimize(none)`.
+    #[inline(always)] async {}; // Inherits `optimize(none)`.
+}
+```
+
 r[attributes.codegen.optimize.closures]
 Closures and [async blocks] without an `optimize` attribute of their own inherit the attribute in effect on the innermost enclosing function, closure, or async block, which may itself be one inherited rather than one written directly. The body of an [async function] inherits the attribute in effect on the function, and the body of an [async closure] inherits the attribute in effect on the closure. Items and [const blocks] within a function do not inherit the attribute in effect on the function, nor do the closures and async blocks within them.
 

From cd54f62a1a222c122a525a4773ac38611df21001 Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Tue, 29 Sep 2026 20:50:25 +0000
Subject: [PATCH 07/11] Reword `optimize` index entry

The `optimize` attribute suggests an optimization goal (or lack
thereof); it doesn't "control" the optimization level.  Let's be more
clear, and let's use the Reference identifiers for the link reference
definitions.
---
 src/attributes.md      | 4 ++--
 src/items/functions.md | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/attributes.md b/src/attributes.md
index 45fbbc534f..f05e5f3bcb 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -255,7 +255,7 @@ The following is an index of all built-in attributes.
   - [`cold`] --- Hint that a function is unlikely to be called.
   - [`naked`] --- Prevent the compiler from emitting a function prologue and epilogue.
   - [`no_builtins`] --- Disables use of certain built-in functions.
-  - [`optimize`] --- Controls the level of optimization to be applied to the function.
+  - [`optimize`] --- Suggest an optimization goal for a function: size, speed, or none.
   - [`target_feature`] --- Configure platform-specific code generation.
   - [`track_caller`] --- Pass the parent call location to `std::panic::Location::caller()`.
   - [`instruction_set`] --- Specify the instruction set used to generate a function's code.
@@ -329,7 +329,7 @@ The following is an index of all built-in attributes.
 [`no_mangle`]: abi.md#the-no_mangle-attribute
 [`no_std`]: names/preludes.md#the-no_std-attribute
 [`non_exhaustive`]: attributes/type_system.md#the-non_exhaustive-attribute
-[`optimize`]: attributes/codegen.md#the-optimize-attribute
+[`optimize`]: attributes.codegen.optimize
 [`panic_handler`]: panic.md#the-panic_handler-attribute
 [`path`]: items/modules.md#the-path-attribute
 [`proc_macro_attribute`]: procedural-macros.md#the-proc_macro_attribute-attribute
diff --git a/src/items/functions.md b/src/items/functions.md
index db10195793..ce8a41b213 100644
--- a/src/items/functions.md
+++ b/src/items/functions.md
@@ -765,7 +765,7 @@ fn foo_oof(#[some_inert_attribute] arg: u8) {
 [`export_name`]: ../abi.md#the-export_name-attribute
 [`link_section`]: ../abi.md#the-link_section-attribute
 [`no_mangle`]: ../abi.md#the-no_mangle-attribute
-[`optimize`]: ../attributes/codegen.md#the-optimize-attribute
+[`optimize`]: attributes.codegen.optimize
 [built-in attributes]: ../attributes.md#built-in-attributes-index
 [trait item]: traits.md
 [method]: associated-items.md#methods

From 46a6fe82b39e865c95f7f6224be29cc21839fa2e Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Tue, 29 Sep 2026 20:50:25 +0000
Subject: [PATCH 08/11] Document that `optimize` conflicts with `naked`

The `optimize` and `naked` attributes can't be used on the same
function.  Let's document that.
---
 src/attributes/codegen.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 3503969fbd..dbb7da4c46 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -223,6 +223,18 @@ The [testing attributes] cannot be applied to a naked function.
 r[attributes.codegen.naked.target_feature]
 The [`target_feature` attribute] cannot be applied to a naked function.
 
+r[attributes.codegen.naked.optimize]
+The [`optimize` attribute] cannot be applied to a naked function. (See [attributes.codegen.optimize.naked].)
+
+```rust,compile_fail,E0736
+# use core::arch::naked_asm;
+#[optimize(size)] // ERROR: Not allowed on a naked function.
+#[unsafe(naked)]
+pub extern "C" fn f() {
+    naked_asm!("ret")
+}
+```
+
 <!-- TODO: Reflexive rules? -->
 
 r[attributes.codegen.naked.abi]
@@ -328,6 +340,18 @@ pub fn f() {
 }
 ```
 
+r[attributes.codegen.optimize.naked]
+The `optimize` attribute cannot be applied to a [naked function]. (See [attributes.codegen.naked.optimize].)
+
+```rust,compile_fail,E0736
+# use core::arch::naked_asm;
+#[optimize(size)] // ERROR: Not allowed on a naked function.
+#[unsafe(naked)]
+pub extern "C" fn f() {
+    naked_asm!("ret")
+}
+```
+
 r[attributes.codegen.optimize.closures]
 Closures and [async blocks] without an `optimize` attribute of their own inherit the attribute in effect on the innermost enclosing function, closure, or async block, which may itself be one inherited rather than one written directly. The body of an [async function] inherits the attribute in effect on the function, and the body of an [async closure] inherits the attribute in effect on the closure. Items and [const blocks] within a function do not inherit the attribute in effect on the function, nor do the closures and async blocks within them.
 
@@ -1045,6 +1069,7 @@ If the address of the function is taken as a function pointer, the low bit of th
 [`Location`]: core::panic::Location
 [`naked_asm!`]: asm
 [`no_mangle`]: abi.no_mangle
+[`optimize` attribute]: attributes.codegen.optimize
 [`target_feature` attribute]: attributes.codegen.target_feature
 [`target_feature` conditional compilation option]: ../conditional-compilation.md#target_feature
 [`track_caller` attribute]: attributes.codegen.track_caller
@@ -1063,6 +1088,7 @@ If the address of the function is taken as a function pointer, the low bit of th
 [function body]: items.fn.body
 [functions]: ../items/functions.md
 [inherent impl]: items.impl.inherent
+[naked function]: attributes.codegen.naked
 ["Rust" ABI]: items.extern.abi.rust
 [rust-abi]: ../items/external-blocks.md#abi
 [target architecture]: ../conditional-compilation.md#target_arch

From b1b68669e5bb3ec43e9457dd85c28acaffd4d852 Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Tue, 20 Oct 2026 07:05:22 +0000
Subject: [PATCH 09/11] Make the `-Copt-level=0` no-op remark a note

Describing how the `optimize` attribute has no effect when
`-Copt-level=0` is set is more appropriate for a nonnormative
admonition rather than in the main body of the Reference.  From a
language perspective, the attribute always has no effect (even if it
does, as a language matter, have a certain meaning and intention).
---
 src/attributes/codegen.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index dbb7da4c46..3f279a72a7 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -273,8 +273,6 @@ r[attributes.codegen.optimize]
 r[attributes.codegen.optimize.intro]
 The *`optimize` [attribute]* suggests an optimization goal for the attributed function: size, speed, or none.
 
-This attribute has no effect if optimizations are disabled (i.e. `opt-level` is `0`).
-
 > [!EXAMPLE]
 > ```rust
 > #[optimize(size)]
@@ -287,6 +285,9 @@ This attribute has no effect if optimizations are disabled (i.e. `opt-level` is
 > pub fn example3() {}
 > ```
 
+> [!NOTE]
+> For `rustc`, the attribute has no effect when optimizations are disabled (`-C opt-level=0`).
+
 r[attributes.codegen.optimize.syntax]
 The syntax for the `optimize` attribute is:
 

From 258e2a27f68236723919dfb86942c5086c166adc Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Wed, 21 Oct 2026 00:57:07 +0000
Subject: [PATCH 10/11] Revise the `optimize` grammar

Let's tighten the scope of the alternation within the grammar for the
`optimize` attribute.
---
 src/attributes/codegen.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 3f279a72a7..4cdbb8253b 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -293,9 +293,7 @@ The syntax for the `optimize` attribute is:
 
 ```grammar,attributes
 @root OptimizeAttribute ->
-      `optimize` `(` `size` `)`
-    | `optimize` `(` `speed` `)`
-    | `optimize` `(` `none` `)`
+    `optimize` `(` ( `size` | `speed` | `none` ) `)`
 ```
 
 r[attributes.codegen.optimize.allowed-positions]

From 13dcb18d8d2d3d9e163d59adf868ec903073a783 Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Wed, 21 Oct 2026 00:57:47 +0000
Subject: [PATCH 11/11] Add examples for `optimize` positions and duplicates

Let's add examples for `optimize` demonstrating the allowed positions
and the behavior when the attribute is repeated on an item.
---
 src/attributes/codegen.md | 48 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 4cdbb8253b..0845b24c5a 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -299,9 +299,57 @@ The syntax for the `optimize` attribute is:
 r[attributes.codegen.optimize.allowed-positions]
 The `optimize` 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].
 
+```rust
+// A free function.
+#[optimize(size)]
+pub fn f() {
+    #[optimize(speed)] || (); // A closure.
+    #[optimize(none)] async {}; // An async block.
+}
+
+pub struct S;
+impl S {
+    // An associated function in an inherent impl.
+    #[optimize(size)]
+    pub fn f(&self) {}
+}
+
+pub trait Tr {
+    // An associated function in a trait with a default definition.
+    #[optimize(speed)]
+    fn f(&self) {}
+}
+
+impl Tr for S {
+    // An associated function in a trait impl.
+    #[optimize(none)]
+    fn f(&self) {}
+}
+```
+
+The attribute is rejected on a function without a body.
+
+```rust,compile_fail
+trait Tr {
+    #[optimize(size)] // ERROR: Not allowed without a body.
+    fn f();
+}
+
+unsafe extern "C" {
+    #[optimize(size)] // ERROR: Not allowed without a body.
+    fn g();
+}
+```
+
 r[attributes.codegen.optimize.duplicates]
 The `optimize` attribute may be used only once on a function.
 
+```rust,compile_fail
+#[optimize(size)]
+#[optimize(speed)] // ERROR: Multiple `optimize` attributes.
+fn f() {}
+```
+
 r[attributes.codegen.optimize.modes]
 The `optimize` attribute supports these modes: