From 45d2a26cc5c87f13354b4abca0510ffa9f5723e1 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Mon, 2 Jun 2025 17:08:50 -0700
Subject: [PATCH 1/4] Unwrap used

---
 src/abi.md | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/src/abi.md b/src/abi.md
index c0f7ed78a..42a7abae8 100644
--- a/src/abi.md
+++ b/src/abi.md
@@ -13,13 +13,9 @@ r[abi.used]
 ## The `used` attribute
 
 r[abi.used.intro]
-The *`used` attribute* can only be applied to [`static` items]. This [attribute] forces the
-compiler to keep the variable in the output object file (.o, .rlib, etc. excluding final binaries)
-even if the variable is not used, or referenced, by any other item in the crate.
-However, the linker is still free to remove such an item.
+The *`used` attribute* can only be applied to [`static` items]. This [attribute] forces the compiler to keep the variable in the output object file (.o, .rlib, etc. excluding final binaries) even if the variable is not used, or referenced, by any other item in the crate. However, the linker is still free to remove such an item.
 
-Below is an example that shows under what conditions the compiler keeps a `static` item in the
-output object file.
+Below is an example that shows under what conditions the compiler keeps a `static` item in the output object file.
 
 ``` rust
 // foo.rs

From c61f0e2806106460b38bb412ad5f2baa8c87b630 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Mon, 2 Jun 2025 17:13:21 -0700
Subject: [PATCH 2/4] Slightly reword the used intro

---
 src/abi.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/abi.md b/src/abi.md
index 42a7abae8..7e5e89347 100644
--- a/src/abi.md
+++ b/src/abi.md
@@ -13,7 +13,7 @@ r[abi.used]
 ## The `used` attribute
 
 r[abi.used.intro]
-The *`used` attribute* can only be applied to [`static` items]. This [attribute] forces the compiler to keep the variable in the output object file (.o, .rlib, etc. excluding final binaries) even if the variable is not used, or referenced, by any other item in the crate. However, the linker is still free to remove such an item.
+The *`used` [attribute]* forces a [`static` item][items.static] to be kept in the output object file (.o, .rlib, etc. excluding final binaries) even if the static is never used, or referenced, by an other item in the crate. However, the linker is still free to remove such an item.
 
 Below is an example that shows under what conditions the compiler keeps a `static` item in the output object file.
 
@@ -131,7 +131,6 @@ r[abi.export_name.edition2024]
 > [!EDITION-2024]
 > Before the 2024 edition it is allowed to use the `export_name` attribute without the `unsafe` qualification.
 
-[`static` items]: items/static-items.md
 [attribute]: attributes.md
 [extern functions]: items/functions.md#extern-function-qualifier
 [external blocks]: items/external-blocks.md

From 2c0ea0bf36691b5a6afe4638905fbc7e63bd0832 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Mon, 2 Jun 2025 17:14:10 -0700
Subject: [PATCH 3/4] Move used example into an example block

---
 src/abi.md | 83 +++++++++++++++++++++++++++---------------------------
 1 file changed, 42 insertions(+), 41 deletions(-)

diff --git a/src/abi.md b/src/abi.md
index 7e5e89347..8d252a872 100644
--- a/src/abi.md
+++ b/src/abi.md
@@ -15,47 +15,48 @@ r[abi.used]
 r[abi.used.intro]
 The *`used` [attribute]* forces a [`static` item][items.static] to be kept in the output object file (.o, .rlib, etc. excluding final binaries) even if the static is never used, or referenced, by an other item in the crate. However, the linker is still free to remove such an item.
 
-Below is an example that shows under what conditions the compiler keeps a `static` item in the output object file.
-
-``` rust
-// foo.rs
-
-// This is kept because of `#[used]`:
-#[used]
-static FOO: u32 = 0;
-
-// This is removable because it is unused:
-#[allow(dead_code)]
-static BAR: u32 = 0;
-
-// This is kept because it is publicly reachable:
-pub static BAZ: u32 = 0;
-
-// This is kept because it is referenced by a public, reachable function:
-static QUUX: u32 = 0;
-
-pub fn quux() -> &'static u32 {
-    &QUUX
-}
-
-// This is removable because it is referenced by a private, unused (dead) function:
-static CORGE: u32 = 0;
-
-#[allow(dead_code)]
-fn corge() -> &'static u32 {
-    &CORGE
-}
-```
-
-``` console
-$ rustc -O --emit=obj --crate-type=rlib foo.rs
-
-$ nm -C foo.o
-0000000000000000 R foo::BAZ
-0000000000000000 r foo::FOO
-0000000000000000 R foo::QUUX
-0000000000000000 T foo::quux
-```
+> [!EXAMPLE]
+> This example that shows under what conditions the compiler keeps a `static` item in the output object file.
+>
+> ```rust
+> // foo.rs
+>
+> // This is kept because of `#[used]`:
+> #[used]
+> static FOO: u32 = 0;
+>
+> // This is removable because it is unused:
+> #[allow(dead_code)]
+> static BAR: u32 = 0;
+>
+> // This is kept because it is publicly reachable:
+> pub static BAZ: u32 = 0;
+>
+> // This is kept because it is referenced by a public, reachable function:
+> static QUUX: u32 = 0;
+>
+> pub fn quux() -> &'static u32 {
+>     &QUUX
+> }
+>
+> // This is removable because it is referenced by a private, unused (dead) function:
+> static CORGE: u32 = 0;
+>
+> #[allow(dead_code)]
+> fn corge() -> &'static u32 {
+>     &CORGE
+> }
+> ```
+>
+> ```console
+> $ rustc -O --emit=obj --crate-type=rlib foo.rs
+>
+> $ nm -C foo.o
+> 0000000000000000 R foo::BAZ
+> 0000000000000000 r foo::FOO
+> 0000000000000000 R foo::QUUX
+> 0000000000000000 T foo::quux
+> ```
 
 r[abi.no_mangle]
 ## The `no_mangle` attribute

From 8f558159515606d0aea7950fa1b541b2979e312b Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Mon, 2 Jun 2025 17:21:12 -0700
Subject: [PATCH 4/4] Add attribute template rules for used

---
 src/abi.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/abi.md b/src/abi.md
index 8d252a872..981fadfd9 100644
--- a/src/abi.md
+++ b/src/abi.md
@@ -58,6 +58,18 @@ The *`used` [attribute]* forces a [`static` item][items.static] to be kept in th
 > 0000000000000000 T foo::quux
 > ```
 
+r[abi.used.syntax]
+The `used` attribute uses the [MetaWord] syntax and thus does not take any inputs.
+
+r[abi.used.allowed-positions]
+The `used` attribute may only be applied to [`static` items][items.static].
+
+r[abi.used.duplicates]
+Only the first instance of `used` on an item is honored. Subsequent `used` attributes are ignored.
+
+> [!NOTE]
+> `rustc` currently warns on subsequent duplicate `used` attributes.
+
 r[abi.no_mangle]
 ## The `no_mangle` attribute