From e77f4e617b7f133eca32caa3f3c408524e2a51ab Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 10 Sep 2024 17:48:13 +0000 Subject: [PATCH] Apply suggestions from PR review --- src/attributes.md | 8 +-- src/attributes/codegen.md | 14 +++--- src/attributes/debugger.md | 14 +++--- src/attributes/derive.md | 2 +- src/attributes/diagnostics.md | 92 +++++++++++++++++------------------ src/attributes/limits.md | 8 +-- src/attributes/testing.md | 4 +- src/attributes/type_system.md | 2 +- 8 files changed, 72 insertions(+), 72 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 1a2ffed7a..ebe7e61cf 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -17,7 +17,7 @@ r[attributes.syntax] >       [_DelimTokenTree_]\ >    | `=` [_Expression_] -r[attributes.general] +r[attributes.intro] An _attribute_ is a general, free-form metadatum that is interpreted according to name, convention, language, and compiler version. Attributes are modeled on Attributes in [ECMA-335], with the syntax coming from [ECMA-334] \(C#). @@ -109,7 +109,7 @@ fn some_unused_variables() { r[attributes.meta] -r[attributes.meta.general] +r[attributes.meta.intro] A "meta item" is the syntax used for the _Attr_ rule by most [built-in attributes]. It has the following grammar: @@ -192,7 +192,7 @@ _MetaListNameValueStr_ | `link(name = "CoreFoundation", kind = "framework")` r[attributes.activity] -r[attributes.activity.general] +r[attributes.activity.intro] 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. @@ -205,7 +205,7 @@ active. All other attributes are inert. r[attributes.tool] -r[attributes.tool.general] +r[attributes.tool.intro] The compiler may allow attributes for external tools where each tool resides in its own module in the [tool prelude]. The first segment of the attribute path is the name of the tool, with one or more additional segments whose diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 33fa0be34..cb27e214d 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -23,7 +23,7 @@ have no effect on a trait function without a body. r[attributes.codgen.inline] -r[attributes.codegen.inline.general] +r[attributes.codegen.inline.intro] The *`inline` [attribute]* suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined. @@ -64,7 +64,7 @@ assumed to exist. r[attributes.codegen.target_feature] -r[attributes.codegen.target_feature.general] +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 @@ -76,17 +76,17 @@ features. It uses the [_MetaListNameValueStr_] syntax with a single key of unsafe fn foo_avx2() {} ``` -r[attributes.codegen.target_features.arch] +r[attributes.codegen.target_feature.arch] Each [target architecture] has a set of features that may be enabled. It is an error to specify a feature for a target architecture that the crate is not being compiled for. -r[attributes.codegen.target_features.precondition] +r[attributes.codegen.target_feature.precondition] It is [undefined behavior] to call a function that is compiled with a feature that is not supported on the current platform the code is running on, *except* if the platform explicitly documents this to be safe. -r[attributes.codegen.target_features.restriction] +r[attributes.codegen.target_feature.restriction-inline] Functions marked with `target_feature` are not inlined into a context that does not support the given features. The `#[inline(always)]` attribute may not be used with a `target_feature` attribute. @@ -361,7 +361,7 @@ otherwise undefined behavior results. ### Behavior -r[attributes.codegen.track_caller.behaviour] +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 implementation behaves as if it walks up the stack from `f`'s frame to find the nearest frame of an @@ -443,7 +443,7 @@ And so on. r[attributes.codegen.track_caller.limits] -r[attributes.codegent.track_caller.hint] +r[attributes.codegen.track_caller.hint] This information is a hint and implementations are not required to preserve it. r[attributes.codegen.track_caller.decay] diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 44e05e81d..40074b5c7 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -8,7 +8,7 @@ The following [attributes] are used for enhancing the debugging experience when r[attributes.debugger.debugger_visualizer] -r[attributes.debugger.debugger_visualizer.general] +r[attributes.debugger.debugger_visualizer.intro] The *`debugger_visualizer` attribute* can be used to embed a debugger visualizer file into the debug information. This enables an improved debugger experience for displaying values in the debugger. @@ -19,14 +19,14 @@ It uses the [_MetaListNameValueStr_] syntax to specify its inputs, and must be s r[attributes.debugger.debugger_visualizer.natvis] -r[attributes.debugger.debugger_visualizer.natvis-general] +r[attributes.debugger.debugger_visualizer.natvis.intro] Natvis is an XML-based framework for Microsoft debuggers (such as Visual Studio and WinDbg) that uses declarative rules to customize the display of types. For detailed information on the Natvis format, refer to Microsoft's [Natvis documentation]. -r[attributes.debugger.debugger_visualizer.natvis-restrictions] +r[attributes.debugger.debugger_visualizer.natvis.restrictions] This attribute only supports embedding Natvis files on `-windows-msvc` targets. -r[attributes.debugger.debugger_visualizer.natvis-path] +r[attributes.debugger.debugger_visualizer.natvis.path] The path to the Natvis file is specified with the `natvis_file` key, which is a path relative to the crate source file: @@ -87,7 +87,7 @@ When viewed under WinDbg, the `fancy_rect` variable would be shown as follows: r[attributes.debugger.debugger_visualizer.gdb] -r[attributes.debugger.debugger_visualizer.gdb-pretty] +r[attributes.debugger.debugger_visualizer.gdb.pretty] GDB supports the use of a structured Python script, called a *pretty printer*, that describes how a type should be visualized in the debugger view. For detailed information on pretty printers, refer to GDB's [pretty printing documentation]. @@ -97,7 +97,7 @@ There are two ways to enable auto-loading embedded pretty printers: For more information, see GDB's [auto-loading documentation]. 1. Create a file named `gdbinit` under `$HOME/.config/gdb` (you may need to create the directory if it doesn't already exist). Add the following line to that file: `add-auto-load-safe-path path/to/binary`. -r[attributes.debugger.debugger_visualizer.gdb-path] +r[attributes.debugger.debugger_visualizer.gdb.path] These scripts are embedded using the `gdb_script_file` key, which is a path relative to the crate source file. @@ -162,7 +162,7 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil r[attributes.debugger.collapse_debuginfo] -r[attributes.debugger.collapse_debuginfo.general] +r[attributes.debugger.collapse_debuginfo.intro] The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site, when generating debuginfo for code calling this macro. diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 03f9fc469..07238c44e 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -3,7 +3,7 @@ r[attributes.derive] -r[attributes.derived.general] +r[attributes.derive.intro] The *`derive` attribute* allows new [items] to be automatically generated for data structures. diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 95264de5c..4f3d99340 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -1,18 +1,18 @@ # Diagnostic attributes -r[attributes.diagnostics] +r[attributes.diagnostic] The following [attributes] are used for controlling or generating diagnostic messages during compilation. ## Lint check attributes -r[attributes.diagnostics.lints] +r[attributes.diagnostic.lint] A lint check names a potentially undesirable coding pattern, such as unreachable code or omitted documentation. -r[attributes.diagnostics.lints.level] +r[attributes.diagnostic.lint.level] The lint attributes `allow`, `expect`, `warn`, `deny`, and `forbid` use the [_MetaListPaths_] syntax to specify a list of lint names to change the lint level for the entity @@ -20,22 +20,22 @@ to which the attribute applies. For any lint check `C`: -r[attributes.diagnostics.lints.allow] +r[attributes.diagnostic.lint.allow] * `#[allow(C)]` overrides the check for `C` so that violations will go unreported. -r[attributes.diagnostics.lints.expect] +r[attributes.diagnostic.lint.expect] * `#[expect(C)]` indicates that lint `C` is expected to be emitted. The attribute will suppress the emission of `C` or issue a warning, if the expectation is unfulfilled. -r[attributes.diagnostics.lints.warn] +r[attributes.diagnostic.lint.warn] * `#[warn(C)]` warns about violations of `C` but continues compilation. -r[attributes.diagnostics.lints.deny] +r[attributes.diagnostic.lint.deny] * `#[deny(C)]` signals an error after encountering a violation of `C`, -r[attributes.diagnostics.lints.forbid] +r[attributes.diagnostic.lint.forbid] * `#[forbid(C)]` is the same as `deny(C)`, but also forbids changing the lint level afterwards, @@ -58,7 +58,7 @@ pub mod m1 { } ``` -r[attributes.diagnostics.lints.override] +r[attributes.diagnostic.lint.override] Lint attributes can override the level specified from a previous attribute, as long as the level does not attempt to change a forbidden lint. Previous attributes are those from a higher level in the syntax tree, or from a @@ -105,7 +105,7 @@ pub mod m3 { ### Lint Reasons -r[attributes.diagnostics.lints.reason] +r[attributes.diagnostic.lint.reason] All lint attributes support an additional `reason` parameter, to give context why a certain attribute was added. This reason will be displayed as part of the lint message if the lint is emitted at the defined level. @@ -142,9 +142,9 @@ pub fn get_path() -> PathBuf { ### The `#[expect]` attribute -r[attributes.diagnostics.expect] +r[attributes.diagnostic.expect] -r[attributes.diagnostics.expect.general] +r[attributes.diagnostic.expect.intro] The `#[expect(C)]` attribute creates a lint expectation for lint `C`. The expectation will be fulfilled, if a `#[warn(C)]` attribute at the same location would result in a lint emission. If the expectation is unfulfilled, because @@ -170,7 +170,7 @@ fn main() { } ``` -r[attributes.lints.expect.fulfilment] +r[attributes.lints.expect.fulfillment] The lint expectation is only fulfilled by lint emissions which have been suppressed by the `expect` attribute. If the lint level is modified in the scope with other level attributes like `allow` or `warn`, the lint emission will be handled accordingly and the @@ -200,7 +200,7 @@ fn select_song() { } ``` -r[attributes.diagnostics.expect.independent] +r[attributes.diagnostic.expect.independent] If the `expect` attribute contains several lints, each one is expected separately. For a lint group it's enough if one lint inside the group has been emitted: @@ -229,7 +229,7 @@ pub fn another_example() { ### Lint groups -r[attributes.lints.groups] +r[attributes.diagnostic.lint.group] Lints may be organized into named groups so that the level of related lints can be adjusted together. Using a named group is equivalent to listing out the lints within that group. @@ -250,7 +250,7 @@ fn example() { } ``` -r[attributes.lints.warnings-group] +r[attributes.diagnostic.lint.group.warnings] There is a special group named "warnings" which includes all lints at the "warn" level. The "warnings" group ignores attribute order and applies to all lints that would otherwise warn within the entity. @@ -270,13 +270,13 @@ fn example_err() { ### Tool lint attributes -r[attributes.lints.tools] +r[attributes.diagnostic.lint.tool] -r[attributes.lints.tools.general] +r[attributes.diagnostic.lint.tool.intro] Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid` lints of certain tools. -r[attributes.lints.tools.activation] +r[attributes.diagnostic.lint.tool.activation] Tool lints only get checked when the associated tool is active. If a lint attribute, such as `allow`, references a nonexistent tool lint, the compiler will not warn about the nonexistent lint until you use the tool. @@ -304,14 +304,14 @@ fn foo() { ## The `deprecated` attribute -r[attributes.diagnostics.deprecated] +r[attributes.diagnostic.deprecated] -r[attributes.diagnostics.deprecated.general] +r[attributes.diagnostic.deprecated.intro] The *`deprecated` attribute* marks an item as deprecated. `rustc` will issue warnings on usage of `#[deprecated]` items. `rustdoc` will show item deprecation, including the `since` version and `note`, if available. -r[attributes.diagnostics.deprectead.syntax] +r[attributes.diagnostic.deprecated.syntax] The `deprecated` attribute has several forms: - `deprecated` --- Issues a generic message. @@ -325,7 +325,7 @@ The `deprecated` attribute has several forms: message. This is typically used to provide an explanation about the deprecation and preferred alternatives. -r[attributes.diagnostics.deprecated.application] +r[attributes.diagnostic.deprecated.application] The `deprecated` attribute may be applied to any [item], [trait item], [enum variant], [struct field], [external block item], or [macro definition]. It cannot be applied to [trait implementation items]. When applied to an item @@ -351,20 +351,20 @@ The [RFC][1270-deprecation.md] contains motivations and more details. ## The `must_use` attribute -r[attributes.diagnostics.must_use] +r[attributes.diagnostic.must_use] -r[attributes.diagnostics.must_use.application] +r[attributes.diagnostic.must_use.application] The *`must_use` attribute* is used to issue a diagnostic warning when a value is not "used". It can be applied to user-defined composite types ([`struct`s][struct], [`enum`s][enum], and [`union`s][union]), [functions], and [traits]. -r[attributes.diagnostics.must_use.syntax] +r[attributes.diagnostic.must_use.syntax] The `must_use` attribute may include a message by using the [_MetaNameValueStr_] syntax such as `#[must_use = "example message"]`. The message will be given alongside the warning. -r[attributes.diagnostics.must_use.types] +r[attributes.diagnostic.must_use.type] When used on user-defined composite types, if the [expression] of an [expression statement] has that type, then the `unused_must_use` lint is violated. @@ -383,7 +383,7 @@ struct MustUse { MustUse::new(); ``` -r[attributes.diagnostics.must_use.function] +r[attributes.diagnostic.must_use.fn] When used on a function, if the [expression] of an [expression statement] is a [call expression] to that function, then the `unused_must_use` lint is violated. @@ -396,7 +396,7 @@ fn five() -> i32 { 5i32 } five(); ``` -r[attributes.diagnostics.must_use.traits] +r[attributes.diagnostic.must_use.trait] When used on a [trait declaration], a [call expression] of an [expression statement] to a function that returns an [impl trait] or a [dyn trait] of that trait violates the `unused_must_use` lint. @@ -414,7 +414,7 @@ fn get_critical() -> impl Critical { get_critical(); ``` -r[attributes.diagnostics.must_use.trait-function] +r[attributes.diagnostic.must_use.trait-function] When used on a function in a trait declaration, then the behavior also applies when the call expression is a function from an implementation of the trait. @@ -432,7 +432,7 @@ impl Trait for i32 { 5i32.use_me(); ``` -r[attributes.diagnostics.must_use.impl-function] +r[attributes.diagnostic.must_use.trait-impl-function] When used on a function in a trait implementation, the attribute does nothing. > Note: Trivial no-op expressions containing the value will not violate the @@ -467,59 +467,59 @@ When used on a function in a trait implementation, the attribute does nothing. ## The `diagnostic` tool attribute namespace -r[attributes.diagnostics.namespace] +r[attributes.diagnostic.namespace] -r[attributes.diagnostics.namespace.general] +r[attributes.diagnostic.namespace.intro] The `#[diagnostic]` attribute namespace is a home for attributes to influence compile-time error messages. The hints provided by these attributes are not guaranteed to be used. -r[attributes.diagnostics.namespace.unknown-invalid-syntax] +r[attributes.diagnostic.namespace.unknown-invalid-syntax] Unknown attributes in this namespace are accepted, though they may emit warnings for unused attributes. Additionally, invalid inputs to known attributes will typically be a warning (see the attribute definitions for details). This is meant to allow adding or discarding attributes and changing inputs in the future to allow changes without the need to keep the non-meaningful attributes or options working. ### The `diagnostic::on_unimplemented` attribute -r[attributes.diagnostics.on_unimplemented] +r[attributes.diagnostic.on_unimplemented] -r[attributes.diagnostics.on_unimplemented.general] +r[attributes.diagnostic.on_unimplemented.intro] The `#[diagnostic::on_unimplemented]` attribute is a hint to the compiler to supplement the error message that would normally be generated in scenarios where a trait is required but not implemented on a type. -r[attributes.diagnostics.on_unimplemented.restriction] +r[attributes.diagnostic.on_unimplemented.restriction] The attribute should be placed on a [trait declaration], though it is not an error to be located in other positions. -r[attributes.diagnostics.on_unimplemented.syntax] +r[attributes.diagnostic.on_unimplemented.syntax] The attribute uses the [_MetaListNameValueStr_] syntax to specify its inputs, though any malformed input to the attribute is not considered as an error to provide both forwards and backwards compatibility. -r[attributes.diagnostics.on_unimplemented.keys] +r[attributes.diagnostic.on_unimplemented.keys] The following keys have the given meaning: * `message` --- The text for the top level error message. * `label` --- The text for the label shown inline in the broken code in the error message. * `note` --- Provides additional notes. -r[attributes.diagnostics.on_unimplemented-note-repetition] +r[attributes.diagnostic.on_unimplemented-note-repetition] The `note` option can appear several times, which results in several note messages being emitted. -r[attributes.diagnostics.on_unimplemented.repetition] +r[attributes.diagnostic.on_unimplemented.repetition] If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. -r[attributes.diagnostics.on_unimplemented.warnings] +r[attributes.diagnostic.on_unimplemented.warnings] Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. -r[attributes.diagnostics.format-string] +r[attributes.diagnostic.format-string] All three options accept a string as an argument, interpreted using the same formatting as a [`std::fmt`] string. -r[attributes.diagnostics.format-parameters] +r[attributes.diagnostic.format-parameters] Format parameters with the given named parameter will be replaced with the following text: * `{Self}` --- The name of the type implementing the trait. * `{` *GenericParameterName* `}` --- The name of the generic argument's type for the given generic parameter. -r[attributes.diagnostics.invalid-formats] +r[attributes.diagnostic.invalid-formats] Any other format parameter will generate a warning, but will otherwise be included in the string as-is. -r[attributes.diagnostics.invalid-string] +r[attributes.diagnostic.invalid-string] Invalid format strings may generate a warning, but are otherwise allowed, but may not display as intended. Format specifiers may generate a warning, but are otherwise ignored. diff --git a/src/attributes/limits.md b/src/attributes/limits.md index b02e9c56a..edfff4aec 100644 --- a/src/attributes/limits.md +++ b/src/attributes/limits.md @@ -6,14 +6,14 @@ The following [attributes] affect compile-time limits. ## The `recursion_limit` attribute -r[attributes.limits.recursion_limits] +r[attributes.limits.recursion_limit] -r[attributes.limits.recursion_limits.application] +r[attributes.limits.recursion_limit.application] The *`recursion_limit` attribute* may be applied at the [crate] level to set the maximum depth for potentially infinitely-recursive compile-time operations like macro expansion or auto-dereference. -r[attributes.limits.recursion_limits.syntax] +r[attributes.limits.recursion_limit.syntax] It uses the [_MetaNameValueStr_] syntax to specify the recursion depth. @@ -49,7 +49,7 @@ r[attributes.limits.type_length_limit] > > For more information, see . -r[attributes.limits.type_length_limit.general] +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. diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 4d9706f60..c36029222 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -12,7 +12,7 @@ enables the [`test` conditional compilation option]. r[attributes.testing.test] -r[attributes.testing.test.general] +r[attributes.testing.test.intro] The *`test` attribute* marks a function to be executed as a test. r[attributes.testing.test.enabled] @@ -56,7 +56,7 @@ fn test_the_thing() -> io::Result<()> { r[attributes.testing.ignore] -r[attributes.testing.ignore.general] +r[attributes.testing.ignore.intro] A function annotated with the `test` attribute can also be annotated with the `ignore` attribute. The *`ignore` attribute* tells the test harness to not execute that function as a test. It will still be compiled when in test mode. diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index a86f205fb..1523e0d26 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -9,7 +9,7 @@ The following [attributes] are used for changing how a type can be used. r[attributes.type-system.non_exhaustive] -r[attributes.type-system.non_exhaustive.general] +r[attributes.type-system.non_exhaustive.intro] The *`non_exhaustive` attribute* indicates that a type or variant may have more fields or variants added in the future.