Explicitly specify syntax forms for each attribute

Author: chorman0773

src/attributes.md

@@ -197,6 +197,7 @@ An attribute is either active or inert. During attribute processing, *active
 attributes* remove themselves from the thing they are on while *inert attributes*
 stay on.
 
+r[attributes.activity.builtin]
 The [`cfg`] and [`cfg_attr`] attributes are active. The [`test`] attribute is
 inert when compiling for tests and active otherwise. [Attribute macros] are
 active. All other attributes are inert.

src/attributes/codegen.md

@@ -32,6 +32,10 @@ function where it is defined.
 > internal heuristics. Incorrectly inlining functions can make the program
 > slower, so this attribute should be used with care.
 
+r[attributes.codegen.inline.syntax]
+The `inline` attribute uses either [_MetaWord_] syntax (for the default form), or [_MetaListIdents_] syntax.
+When using [_MetaListIdents_] form, only a single ident is permitted.
+
 r[attributes.codegen.inline.modes]
 There are three ways to use the inline attribute:
 
@@ -48,25 +52,46 @@ There are three ways to use the inline attribute:
 
 r[attributes.codegen.cold]
 
+r[attributes.codegen.cold.intro]
 The *`cold` [attribute]* suggests that the attributed function is unlikely to
 be called.
 
+> [!NOTE]
+> In particular, it indicates that branches that lead to such a call are unlikely to be taken.
+
+r[attributes.codegen.cold.syntax]
+The `cold` attribute uses the [_MetaWord_] syntax.
+
 ## The `no_builtins` attribute
 
 r[attributes.codegen.no_builtins]
 
+r[attributes.codegen.no_builtins.intro]
 The *`no_builtins` [attribute]* may be applied at the crate level to disable
 optimizing certain code patterns to invocations of library functions that are
 assumed to exist.
 
+> [!NOTE]
+> Such library functions may include, but are not limited to, C routines such as `memcpy` or `memset`.
+
+> [!WARN]
+> A crate using `no_builtins` does not guarantee that the crate will be free from calls to such functions, even if it does not call the routines explicit.
+> For example, the standard library implementation may still call such functions.
+
+r[attributes.codegen.no_builtins.syntax]
+The `no_builtins` attribute uses the [_MetaWord_] syntax.
+
 ## The `target_feature` attribute
 
 r[attributes.codegen.target_feature]
 
 r[attributes.codegen.target_feature.intro]
 The *`target_feature` [attribute]* may be applied to a function to
 enable code generation of that function for specific platform architecture
-features. It uses the [_MetaListNameValueStr_] syntax with a single key of
+features.
+
+r[attributes.codegen.target_feature.syntax]
+The `target_feature` attribute uses the [_MetaListNameValueStr_] syntax with a single key of
 `enable` whose value is a string of comma-separated feature names to enable.
 
 ```rust
@@ -182,7 +207,6 @@ Reference Manual], or elsewhere on [developer.arm.com].
 > or disabled together if used:
 > - `paca` and `pacg`, which LLVM currently implements as one feature.
 
-
 Feature        | Implicitly Enables | Feature Name
 ---------------|--------------------|-------------------
 `aes`          | `neon`         | FEAT_AES & FEAT_PMULL --- Advanced <abbr title="Single Instruction Multiple Data">SIMD</abbr> AES & PMULL instructions
@@ -354,6 +378,9 @@ r[attributes.codegen.track_caller.allowed-positions]
 The `track_caller` attribute may be applied to any function with [`"Rust"` ABI][rust-abi]
 with the exception of the entry point `fn main`.
 
+r[attributes.codegen.track_caller.syntax]
+The `track_caller` attribute uses the [_MetaWord_] syntax.
+
 r[attributes.codegen.track_caller.traits]
 When applied to functions and methods in trait declarations, the attribute applies to all implementations. If the trait provides a
 default implementation with the attribute, then the attribute also applies to override implementations.
@@ -364,8 +391,6 @@ implementations, otherwise undefined behavior results. When applied to a functio
 available to an `extern` block, the declaration in the `extern` block must also have the attribute,
 otherwise undefined behavior results.
 
-### Behavior
-
 r[attributes.codegen.track_caller.behavior]
 Applying the attribute to a function `f` allows code within `f` to get a hint of the [`Location`] of
 the "topmost" tracked call that led to `f`'s invocation. At the point of observation, an
@@ -385,7 +410,7 @@ fn f() {
 > Note: because the resulting `Location` is a hint, an implementation may halt its walk up the stack
 > early. See [Limitations](#limitations) for important caveats.
 
-#### Examples
+### Examples
 
 When `f` is called directly by `calls_f`, code in `f` observes its callsite within `calls_f`:
 
@@ -464,7 +489,6 @@ trait object whose methods are attributed.
 > creation of a shim hides the implicit parameter from callers of the function pointer, preserving
 > soundness.
 
-[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu
 [`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature
 [`is_x86_feature_detected`]: ../../std/arch/macro.is_x86_feature_detected.html
@@ -493,8 +517,6 @@ This allows mixing more than one instruction set in a single program on CPU arch
 r[attributes.codegen.instruction_set.syntax]
 It uses the [_MetaListPath_] syntax, and a path comprised of the architecture family name and instruction set name.
 
-[_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax
-
 r[attributes.codegen.instruction_set.target-limits]
 It is a compilation error to use the `instruction_set` attribute on a target that does not support it.
 
@@ -519,3 +541,8 @@ Using the `instruction_set` attribute has the following effects:
 
 * If the address of the function is taken as a function pointer, the low bit of the address will be set to 0 (arm) or 1 (thumb) depending on the instruction set.
 * Any inline assembly in the function must use the specified instruction set instead of the target default.
+
+[_MetaWord_]: ../attributes.md#meta-item-attribute-syntax
+[_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax
+[_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax
+[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax

src/attributes/derive.md

@@ -39,11 +39,17 @@ You can implement `derive` for your own traits through [procedural macros].
 ## The `automatically_derived` attribute
 
 r[attributes.derive.automatically_derived]
+
+r[attributes.derive.automatically_derived.intro]
 The *`automatically_derived` attribute* is automatically added to
 [implementations] created by the `derive` attribute for built-in traits. It
 has no direct effect, but it may be used by tools and diagnostic lints to
 detect these automatically generated implementations.
 
+r[attributes.derive.automatically_derived.syntax]
+The `automatically_derived` attribute uses the [_MetaWord_] syntax
+
+[_MetaWord_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax
 [`impl` item]: ../items/implementations.md
 [items]: ../items.md

src/attributes/diagnostics.md

@@ -87,6 +87,9 @@ pub mod m2 {
 }
 ```
 
+r[attributes.diagnostics.lint.override-forbid]
+It is an error to specify a lint level attribute weaker than `deny` that overrides a `forbid` in effect for that item.
+
 This example shows how one can use `forbid` to disallow uses of `allow` or
 `expect` for that lint check:
 
@@ -358,6 +361,9 @@ r[attributes.diagnostics.must_use.intro]
 The *`must_use` attribute* is used to issue a diagnostic warning when a value
 is not "used".
 
+r[attributes.diagnostics.must_use.syntax]
+The `must_use` attribute uses either the [_MetaWord_] syntax, or the [_MetaNameValueStr_] syntax.
+
 r[attributes.diagnostics.must_use.allowed-positions]
 The `must_use` attribute can be applied to user-defined composite types
 ([`struct`s][struct], [`enum`s][enum], and [`union`s][union]), [functions],
@@ -561,6 +567,7 @@ error[E0277]: My Message for `ImportantTrait<i32>` implemented for `String`
 ```
 
 [Clippy]: https://github.com/rust-lang/rust-clippy
+[_MetaWord_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaNameValueStr_]: ../attributes.md#meta-item-attribute-syntax

src/attributes/testing.md

@@ -14,6 +14,9 @@ r[attributes.testing.test]
 r[attributes.testing.test.intro]
 The *`test` attribute* marks a function to be executed as a test.
 
+r[attributes.testing.test.syntax]
+The `test` attribute uses the [_MetaWord_] syntax.
+
 r[attributes.testing.test.enabled]
 These functions are only compiled when in test mode.
 
@@ -60,8 +63,10 @@ A function annotated with the `test` attribute can also be annotated with the
 execute that function as a test. It will still be compiled when in test mode.
 
 r[attributes.testing.ignore.syntax]
-The `ignore` attribute may optionally be written with the [_MetaNameValueStr_]
-syntax to specify a reason why the test is ignored.
+The `ignore` attribute uses either the [_MetaWord_] syntax or the [_MetaNameValueStr_] syntax.
+
+r[attributes.testing.ignore.reason]
+The value in the case of using the [_MetaNameValueStr_] syntax is a reason for the test being ignored.
 
 ```rust
 #[test]
@@ -82,11 +87,14 @@ r[attributes.testing.should_panic.intro]
 A function annotated with the `test` attribute that returns `()` can also be
 annotated with the `should_panic` attribute.
 
+r[attributes.testing.should_panic.syntax]
+The `should_panic` attribute uses the [_MetaWord_] syntax, [_MetaNameValueStr_] syntax, or the [_MetaListNameValueStr_] syntax.
+
 r[attributes.testing.should_panic.behavior]
 The *`should_panic` attribute*
 makes the test only pass if it actually panics.
 
-r[attributes.testing.should_panic.syntax]
+r[attributes.testing.should_panic.expected]
 The `should_panic` attribute may optionally take an input string that must
 appear within the panic message. If the string is not found in the message,
 then the test will fail. The string may be passed using the
@@ -101,6 +109,7 @@ fn mytest() {
 }
 ```
 
+[_MetaWord_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [`Termination`]: std::process::Termination