Merge pull request #1917 from ehuss/type_length_limit

Update `type_length_limit` to use the attribute template

Author: traviscross

docs/attribute-template.md

@@ -6,6 +6,7 @@ When an attribute (or a new attribute position in the grammar) is added, be sure
 
 ----
 
+<!-- template:attributes -->
 r[PARENT.example]
 ## The `example` attribute
 
@@ -14,7 +15,8 @@ The *`example` [attribute][attributes]* ...give a high level description.
 
 > [!EXAMPLE]
 > ```rust
-> // This should be a very basic example showing the attribute used in some way.
+> // This should be a very basic example showing the attribute
+> // used in some way.
 > #[example]
 > fn some_meaningful_name() {}
 > ```
@@ -24,19 +26,70 @@ Describe the accepted syntax of this attribute. You can either explain that it u
 
 ----
 
-The `example` attribute uses the [MetaWord] syntax and thus does not take any inputs.
+The `example` attribute uses the [MetaWord] syntax.
 
 ----
 
 The `example` attribute uses the [MetaListPaths] syntax to specify a list of ...
 
 ----
 
+The `example` attribute uses the [MetaWord] and [MetaNameValueStr] syntaxes.
+
+----
+
+The `example` attribute uses the [MetaWord], [MetaListPaths], and [MetaNameValueStr] syntaxes.
+
+----
+
+The `example` attribute uses the [MetaNameValueStr] syntax. Accepted values are `"X"` and `"Y"`.
+
+----
+
+The `example` attribute uses the [MetaNameValueStr] syntax. The value in the string must be ...
+
+----
+
+The `example` attribute has these forms:
+
+- [MetaWord]
+  > [!EXAMPLE]
+  > ```rust
+  > #[example]
+  > fn f() {}
+  > ```
+
+- [MetaNameValueStr] --- The given string must ...
+  > [!EXAMPLE]
+  > ```rust
+  > #[example = "example"]
+  > fn f() {}
+  > ```
+
+- [MetaListNameValueStr] --- As with the [MetaNameValueStr] syntax, the given string must ...
+  > [!EXAMPLE]
+  > ```rust
+  > #[example(inner = "example")]
+  > fn f() {}
+  > ```
+
+----
+
 The syntax for the `example` attribute is:
 
 ```grammar,attributes
 @root ExampleAttribute -> `example` `(` ... `)`
 ```
+----
+
+r[PARENT.example.syntax.foo]
+The [MetaNameValueStr] form of the `example` attribute provides a way to specify the foo.
+
+> [!EXAMPLE]
+> ```rust
+> #[example = "example"]
+> fn some_meaningful_name() {}
+> ```
 
 r[PARENT.example.allowed-positions]
 Explain the valid positions where this attribute may be used.
@@ -60,10 +113,7 @@ The `example` attribute is allowed anywhere attributes are allowed.
 If there are unused attribute warnings, or if rustc is incorrectly accepting some positions, include a note about these.
 
 > [!NOTE]
-> `rustc` currently warns in other positions, but this may be rejected in the future.
-
-> [!NOTE]
-> `rustc` currently warns on some positions where it is ignored, but this may become an error in the future.
+> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
 
 ----
 
@@ -72,29 +122,40 @@ Explain the behavior if the attribute is specified multiple times on an element.
 
 ----
 
-Duplicate instances of the `example` attribute on the same ... have no effect.
+The `example` attribute may be used any number of times on a form.
 
 ----
 
-The `example` attribute may only be specified once on a [THING].
+Using `example` more than once on a form has the same effect as using it once.
 
 ----
 
-Only the first instance of `example` on an item is honored. Subsequent `example` attributes are ignored.
+The `example` attribute may be used only once on ...
+
+----
+
+Only the first use of `example` on an item has effect.
+
+> [!NOTE]
+> `rustc` lints against any use following the first. This may become an error in the future.
 
 > [!NOTE]
-> `rustc` currently warns on subsequent duplicate `example` attributes. This may become an error in the future.
+> `rustc` lints against any use following the first with a future-compatibility warning. This may become an error in the future.
 
 ----
 
-Only the last instance of `example` on an item is honored. Previous `example` attributes are ignored.
+Only the last use of `example` on an item has effect.
 
 > [!NOTE]
-> `rustc` currently warns on preceding duplicate `example` attributes. This may become an error in the future.
+> `rustc` lints against any use preceding the last. This may become an error in the future.
 
----
+----
+
+Only the last use of `example` on an item is used to ...
+
+----
 
-If the `example` attribute is specified multiple times on an item, then the combination of all the specified values is used as ...explain how they are merged.
+If the `example` attribute is used more than once on an item, then the combination of all the specified values is used as ...explain how they are merged.
 
 ----
 

src/attributes/codegen.md

@@ -82,6 +82,7 @@ The [`track_caller`](#the-track_caller-attribute) attribute cannot be applied to
 r[attributes.codegen.naked.testing]
 The [testing attributes](testing.md) cannot be applied to a naked function.
 
+<!-- template:attributes -->
 r[attributes.codegen.no_builtins]
 ## The `no_builtins` attribute
 
@@ -105,7 +106,7 @@ r[attributes.codegen.no_builtins.duplicates]
 Only the first use of the `no_builtins` attribute has effect.
 
 > [!NOTE]
-> `rustc` currently lints against uses following the first.
+> `rustc` lints against any use following the first.
 
 r[attributes.codegen.target_feature]
 ## The `target_feature` attribute

src/attributes/derive.md

@@ -1,3 +1,4 @@
+<!-- template:attributes -->
 r[attributes.derive]
 # Derive
 
@@ -36,10 +37,10 @@ r[attributes.derive.syntax]
 The `derive` attribute uses the [MetaListPaths] syntax to specify a list of paths to [derive macros] to invoke.
 
 r[attributes.derive.allowed-positions]
-The `derive` attribute may be applied to [structs][items.struct], [enums][items.enum], and [unions][items.union].
+The `derive` attribute may only be applied to [structs][items.struct], [enums][items.enum], and [unions][items.union].
 
 r[attributes.derive.duplicates]
-The `derive` attribute may be specified multiple times on an item, with all derive macros listed in all attributes being invoked.
+The `derive` attribute may be used any number of times on an item. All derive macros listed in all attributes are invoked.
 
 r[attributes.derive.stdlib]
 The `derive` attribute is exported in the standard library prelude as [`core::prelude::v1::derive`].
@@ -63,6 +64,7 @@ The built-in derives include the [`automatically_derived` attribute][attributes.
 r[attributes.derive.behavior]
 During macro expansion, for each element in the list of derives, the corresponding derive macro expands to zero or more [items].
 
+<!-- template:attributes -->
 r[attributes.derive.automatically_derived]
 ## The `automatically_derived` attribute
 
@@ -84,19 +86,19 @@ The *`automatically_derived` [attribute][attributes]* is used to annotate an [im
 > ```
 
 r[attributes.derive.automatically_derived.syntax]
-The `automatically_derived` attribute uses the [MetaWord] syntax and so does not accept any arguments.
+The `automatically_derived` attribute uses the [MetaWord] syntax.
 
 r[attributes.derive.automatically_derived.allowed-positions]
-The `automatically_derived` attribute may be placed on an [implementation].
+The `automatically_derived` attribute may only be applied to an [implementation].
 
 > [!NOTE]
-> `rustc` currently accepts the attribute in other positions but lints against it.
+> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
 
 r[attributes.derive.automatically_derived.duplicates]
-Duplicate instances of the `automatically_derived` attribute on the same implementation have no effect.
+Using `automatically_derived` more than once on an implementation has the same effect as using it once.
 
 > [!NOTE]
-> `rustc` lints against duplicate use of this attribute on uses following the first.
+> `rustc` lints against any use following the first.
 
 r[attributes.derive.automatically_derived.behavior]
 The `automatically_derived` attribute has no behavior.

src/attributes/limits.md

@@ -40,34 +40,48 @@ a!{}
 (|_: &u8| {})(&&&1);
 ```
 
+<!-- template:attributes -->
 r[attributes.limits.type_length_limit]
 ## The `type_length_limit` attribute
 
+r[attributes.limits.type_length_limit.intro]
+The *`type_length_limit` [attribute][attributes]* sets the maximum number of type substitutions allowed when constructing a concrete type during monomorphization.
+
 > [!NOTE]
-> This limit is only enforced when the nightly `-Zenforce-type-length-limit` flag is active.
+> `rustc` only enforces the limit when the nightly `-Zenforce-type-length-limit` flag is active.
 >
-> For more information, see <https://github.com/rust-lang/rust/pull/127670>.
+> For more information, see [Rust PR #127670](https://github.com/rust-lang/rust/pull/127670).
 
-r[attributes.limits.type_length_limit.intro]
-The *`type_length_limit` attribute* limits the maximum number of type
-substitutions made when constructing a concrete type during monomorphization.
+> [!EXAMPLE]
+> <!-- ignore: not enforced without nightly flag -->
+> ```rust,ignore
+> #![type_length_limit = "4"]
+>
+> fn f<T>(x: T) {}
+>
+> // This fails to compile because monomorphizing to
+> // `f::<((((i32,), i32), i32), i32)>` requires more
+> // than 4 type elements.
+> f(((((1,), 2), 3), 4));
+> ```
+
+> [!NOTE]
+> The default value in `rustc` is `1048576`.
 
 r[attributes.limits.type_length_limit.syntax]
-It is applied at the [crate] level, and uses the [MetaNameValueStr] syntax
-to set the limit based on the number of type substitutions.
+The `type_length_limit` attribute uses the [MetaNameValueStr] syntax. The value in the string must be a non-negative number.
 
-> [!NOTE]
-> The default in `rustc` is 1048576.
+r[attributes.limits.type_length_limit.allowed-positions]
+The `type_length_limit` attribute may only be applied to the crate root.
 
-```rust,ignore
-#![type_length_limit = "4"]
+> [!NOTE]
+> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
 
-fn f<T>(x: T) {}
+r[attributes.limits.type_length_limit.duplicates]
+Only the first use of `type_length_limit` on an item has effect.
 
-// This fails to compile because monomorphizing to
-// `f::<((((i32,), i32), i32), i32)>` requires more than 4 type elements.
-f(((((1,), 2), 3), 4));
-```
+> [!NOTE]
+> `rustc` lints against any use following the first. This may become an error in the future.
 
 [attributes]: ../attributes.md
 [crate]: ../crates-and-source-files.md

src/attributes/testing.md

@@ -6,6 +6,7 @@ tests. Compiling a crate in "test" mode enables building the test functions
 along with a test harness for executing the tests. Enabling the test mode also
 enables the [`test` conditional compilation option].
 
+<!-- template:attributes -->
 r[attributes.testing.test]
 ## The `test` attribute
 
@@ -23,7 +24,7 @@ The *`test` [attribute][attributes]* marks a function to be executed as a test.
 > ```
 
 r[attributes.testing.test.syntax]
-The `test` attribute uses the [MetaWord] syntax and thus does not take any inputs.
+The `test` attribute uses the [MetaWord] syntax.
 
 r[attributes.testing.test.allowed-positions]
 The `test` attribute may only be applied to [free functions] that are monomorphic, that take no arguments, and where the return type implements the [`Termination`] trait.
@@ -34,10 +35,10 @@ The `test` attribute may only be applied to [free functions] that are monomorphi
 > * `Result<T, E> where T: Termination, E: Debug`
 
 r[attributes.testing.test.duplicates]
-Only the first instance of `test` on a function is honored.
+Only the first use of `test` on a function has effect.
 
 > [!NOTE]
-> Subsequent `test` attributes are currently ignored and `rustc` warns about these.
+> `rustc` lints against any use following the first. This may become an error in the future.
 
 <!-- TODO: This is a minor lie. Currently rustc warns that duplicates are ignored, but it then generates multiple test entries with the same name. I would vote for rejecting this in the future. -->
 
@@ -71,6 +72,7 @@ In particular:
 > }
 > ```
 
+<!-- template:attributes -->
 r[attributes.testing.ignore]
 ## The `ignore` attribute
 
@@ -90,7 +92,7 @@ The *`ignore` [attribute][attributes]* can be used with the [`test` attribute][a
 > The `rustc` test harness supports the `--include-ignored` flag to force ignored tests to be run.
 
 r[attributes.testing.ignore.syntax]
-The `ignore` attribute uses either the [MetaWord] or [MetaNameValueStr] syntax.
+The `ignore` attribute uses the [MetaWord] and [MetaNameValueStr] syntaxes.
 
 r[attributes.testing.ignore.reason]
 The [MetaNameValueStr] form of the `ignore` attribute provides a way to specify a reason why the test is ignored.
@@ -105,20 +107,21 @@ The [MetaNameValueStr] form of the `ignore` attribute provides a way to specify
 > ```
 
 r[attributes.testing.ignore.allowed-positions]
-The `ignore` attribute may be applied to functions annotated with the `test` attribute.
+The `ignore` attribute may only be applied to functions annotated with the `test` attribute.
 
 > [!NOTE]
-> `rustc` currently warns when `ignore` is used in some other situations. This may become an error in the future.
+> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
 
 r[attributes.testing.ignore.duplicates]
-Only the first instance of `ignore` on a function is honored.
+Only the first use of `ignore` on a function has effect.
 
 > [!NOTE]
-> `rustc` currently ignores duplicate `ignore` 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.testing.ignore.behavior]
 Ignored tests are still compiled when in test mode, but they are not executed.
 
+<!-- template:attributes -->
 r[attributes.testing.should_panic]
 ## The `should_panic` attribute
 
@@ -135,7 +138,7 @@ The *`should_panic` [attribute][attributes]* causes a test to pass only if the [
 > ```
 
 r[attributes.testing.should_panic.syntax]
-The `should_panic` attribute has one of the following forms:
+The `should_panic` attribute has these forms:
 
 - [MetaWord]
   > [!EXAMPLE]
@@ -165,13 +168,13 @@ r[attributes.testing.should_panic.allowed-positions]
 The `should_panic` attribute may only be applied to functions annotated with the `test` attribute.
 
 > [!NOTE]
-> `rustc` currently accepts this attribute in other positions with a warning. This may become a hard error in the future.
+> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
 
 r[attributes.testing.should_panic.duplicates]
-Only the first instance of `should_panic` on a function is honored.
+Only the first use of `should_panic` on a function has effect.
 
 > [!NOTE]
-> `rustc` currently ignores subsequent `should_panic` attributes and emits a future-compatibility warning. This may become a hard error in the future.
+> `rustc` lints against any use following the first with a future-compatibility warning. This may become an error in the future.
 
 r[attributes.testing.should_panic.expected]
 When the [MetaNameValueStr] form or the [MetaListNameValueStr] form with the `expected` key is used, the given string must appear somewhere within the panic message for the test to pass.