Merge pull request #1896 from ehuss/link_name

Update `link_name` to use the attribute template

Author: traviscross

src/attributes/derive.md

@@ -96,7 +96,7 @@ r[attributes.derive.automatically_derived.duplicates]
 Duplicate instances of the `automatically_derived` attribute on the same implementation have no effect.
 
 > [!NOTE]
-> `rustc` lints against duplicate use of this attribute.
+> `rustc` lints against duplicate use of this attribute on uses following the first.
 
 r[attributes.derive.automatically_derived.behavior]
 The `automatically_derived` attribute has no behavior.

src/items/extern-crates.md

@@ -104,7 +104,7 @@ r[items.extern-crate.no_link.duplicates]
 Duplicate instances of the `no_link` attribute are ignored.
 
 > [!NOTE]
-> `rustc` lints against duplicate use  of this attribute.
+> `rustc` lints against duplicate use of this attribute.
 
 [identifier]: ../identifiers.md
 [RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md

src/items/external-blocks.md

@@ -395,22 +395,33 @@ r[items.extern.attributes.link_name]
 ### The `link_name` attribute
 
 r[items.extern.attributes.link_name.intro]
-The *`link_name` attribute* may be specified on declarations inside an `extern`
-block to indicate the symbol to import for the given function or static.
+The *`link_name` [attribute][attributes]* may be applied to declarations inside an `extern` block to specify the symbol to import for the given function or static.
+
+> [!EXAMPLE]
+> ```rust
+> unsafe extern "C" {
+>     #[link_name = "actual_symbol_name"]
+>     safe fn name_in_rust();
+> }
+> ```
 
 r[items.extern.attributes.link_name.syntax]
-It uses the [MetaNameValueStr] syntax to specify the name of the symbol.
+The `link_name` attribute uses the [MetaNameValueStr] syntax.
 
-```rust
-unsafe extern {
-    #[link_name = "actual_symbol_name"]
-    safe fn name_in_rust();
-}
-```
+r[items.extern.attributes.link_name.allowed-positions]
+The `link_name` attribute may only be applied to a function or static item in an `extern` block.
 
-r[items.extern.attributes.link_name.exclusive]
-Using this attribute with the `link_ordinal` attribute will result in a
-compiler error.
+> [!NOTE]
+> `rustc` currently accepts and ignores the attribute in other positions but lints against it. This may become a hard error in the future.
+
+r[items.extern.attributes.link_name.duplicates]
+Only the last instance of `link_name` on an item is used to determine the symbol name.
+
+> [!NOTE]
+> `rustc` lints against duplicate use of this attribute on uses preceding the last. This may become a hard error in the future.
+
+r[items.extern.attributes.link_name.link_ordinal]
+The `link_name` attribute may not be used with the [`link_ordinal`] attribute.
 
 r[items.extern.attributes.link_ordinal]
 ### The `link_ordinal` attribute
@@ -461,3 +472,4 @@ restrictions as [regular function parameters].
 [statics]: static-items.md
 [unwind-behavior]: functions.md#unwinding
 [value namespace]: ../names/namespaces.md
+[`link_ordinal`]: items.extern.attributes.link_ordinal