From 78c712d65a476d5b2b639e8cef381a4032b5ddca Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Thu, 21 Nov 2024 14:47:52 -0500 Subject: [PATCH 1/2] Explicitly specify syntax forms for each attribute --- src/attributes.md | 1 + src/attributes/codegen.md | 43 ++++++++++++++++++++++++++++------- src/attributes/derive.md | 6 +++++ src/attributes/diagnostics.md | 7 ++++++ src/attributes/testing.md | 15 +++++++++--- 5 files changed, 61 insertions(+), 11 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index f537e4cd2..7d4bdc37d 100644 --- a/src/attributes.md +++ b/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. diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 297d6436f..aa9e5cab1 100644 --- a/src/attributes/codegen.md +++ b/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,17 +52,35 @@ 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] @@ -66,7 +88,10 @@ 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 SIMD 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 \ No newline at end of file diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 6a61dbf78..d8c5e2859 100644 --- a/src/attributes/derive.md +++ b/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 diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index eb5caf2e6..fdbfd47c6 100644 --- a/src/attributes/diagnostics.md +++ b/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` 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 diff --git a/src/attributes/testing.md b/src/attributes/testing.md index d245da66b..f94e526d6 100644 --- a/src/attributes/testing.md +++ b/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 From 636e625916f8d5d48ad88e327d07acf37504f886 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Thu, 21 Nov 2024 14:50:45 -0500 Subject: [PATCH 2/2] Fix: File must end with a newline --- src/attributes/codegen.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index aa9e5cab1..76b72435f 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -545,4 +545,4 @@ Using the `instruction_set` attribute has the following effects: [_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 \ No newline at end of file +[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax