From 9e4d72671d3fbb6dcb456422d171171d971170fb Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 31 Oct 2024 14:13:46 -0700 Subject: [PATCH] Rule annotation cleanup A few things for cleanup: - Fix spelling and formatting - Remove rules in a list. The list is more of an index, the items aren't intended to be rules themselves. - Use some more consistent naming. - Use plurals where appropriate. - Avoid generic "constraint" terminology. --- src/items.md | 25 --------------- src/items/associated-items.md | 23 +++++++------- src/items/constant-items.md | 4 +-- src/items/enumerations.md | 16 +++++----- src/items/extern-crates.md | 2 +- src/items/external-blocks.md | 49 +++++++++++++++-------------- src/items/functions.md | 11 +++---- src/items/generics.md | 12 ++++---- src/items/implementations.md | 8 ++--- src/items/modules.md | 4 +-- src/items/static-items.md | 10 +++--- src/items/traits.md | 58 +++++++++++++++++------------------ src/items/type-aliases.md | 8 ++--- src/items/unions.md | 8 ++--- src/items/use-declarations.md | 42 +++++++++++++------------ 15 files changed, 129 insertions(+), 151 deletions(-) diff --git a/src/items.md b/src/items.md index e3763d457..d5733491c 100644 --- a/src/items.md +++ b/src/items.md @@ -44,43 +44,18 @@ execution, and may reside in read-only memory. r[items.kinds] There are several kinds of items: -r[items.kind-modules] * [modules] - -r[items.kind-extern-crate] * [`extern crate` declarations] - -r[items.kind-use] * [`use` declarations] - -r[items.kind-fn] * [function definitions] - -r[items.kind-type] * [type definitions] - -r[items.kind-struct] * [struct definitions] - -r[items.kind-enum] * [enumeration definitions] - -r[items.kind-union] * [union definitions] - -r[items.kind-const] * [constant items] - -r[items.kind-static] * [static items] - -r[items.kind-trait] * [trait definitions] - -r[items.kind-impl] * [implementations] - -r[items.kind-extern] * [`extern` blocks] r[items.locations] diff --git a/src/items/associated-items.md b/src/items/associated-items.md index d7ba4ea01..3df2e0eee 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -13,7 +13,7 @@ r[items.associated.syntax] r[items.associated.intro] *Associated Items* are the items declared in [traits] or defined in [implementations]. They are called this because they are defined on an associate -type — the type in the implementation +type — the type in the implementation. r[items.associated.kinds] They are a subset of the kinds of items you can declare in a module. @@ -52,7 +52,7 @@ function body is replaced with a `;`. r[items.associated.name] The identifier is the name of the function. -r[items.associated.constraint] +r[items.associated.same-signature] The generics, parameter list, return type, and where clause of the associated function must be the same as the associated function declarations's. @@ -111,7 +111,7 @@ Associated functions whose first parameter is named `self` are called *methods* and may be invoked using the [method call operator], for example, `x.foo()`, as well as the usual function call notation. -r[items.associated.fn.method.constraint] +r[items.associated.fn.method.self-ty] If the type of the `self` parameter is specified, it is limited to types resolving to one generated by the following grammar (where `'lt` denotes some arbitrary lifetime): @@ -121,7 +121,6 @@ P = &'lt S | &'lt mut S | Box | Rc | Arc | Pin

S = Self | P ``` -r[items.associated.fn.method.self-ty] The `Self` terminal in this grammar denotes a type resolving to the implementing type. This can also include the contextual type alias `Self`, other type aliases, or associated type projections resolving to the implementing type. @@ -214,7 +213,7 @@ let circle_shape = Circle::new(); let bounding_box = circle_shape.bounding_box(); ``` -r[items.associated.fn.params-edition2015] +r[items.associated.fn.params.edition2015] > **Edition differences**: In the 2015 edition, it is possible to declare trait > methods with anonymous parameters (e.g. `fn foo(u8)`). This is deprecated and > an error as of the 2018 edition. All parameters must have an argument name. @@ -233,7 +232,7 @@ r[items.associated.type] r[items.associated.type.intro] *Associated types* are [type aliases] associated with another type. -r[items.associated.type.constraint] +r[items.associated.type.restrictions] Associated types cannot be defined in [inherent implementations] nor can they be given a default implementation in traits. @@ -256,9 +255,9 @@ type Assoc: Bounds where WhereBounds; ``` r[items.associated.type.name] -The identifier is the name of the declared type alias +The identifier is the name of the declared type alias. -r[items.associated.type.constraint-impl] +r[items.associated.type.impl-fulfillment] The optional trait bounds must be fulfilled by the implementations of the type alias. r[items.associated.type.sized] @@ -268,7 +267,7 @@ r[items.associated.type.def] An *associated type definition* defines a type alias for the implementation of a trait on a type -r[items.associated.type.restriction-def] +r[items.associated.type.def.restriction] They are written similarly to an *associated type declaration*, but cannot contain `Bounds`, but instead must contain a `Type`: @@ -405,7 +404,7 @@ where clauses, dependent on functions in the trait and how the GAT is used. Thes rules may be loosened in the future; updates can be found [on the generic associated types initiative repository](https://rust-lang.github.io/generic-associated-types-initiative/explainer/required_bounds.html). -r[items.associated.type.generic-where-clause.constraint-valid-fn] +r[items.associated.type.generic-where-clause.valid-fn] In a few words, these where clauses are required in order to maximize the allowed definitions of the associated type in impls. To do this, any clauses that *can be proven to hold* on functions (using the parameters of the function or trait) @@ -422,7 +421,7 @@ In the above, on the `next` function, we can prove that `Self: 'a`, because of the implied bounds from `&'a mut self`; therefore, we must write the equivalent bound on the GAT itself: `where Self: 'x`. -r[items.associated.type.generic-where-clause.constraint-intersection] +r[items.associated.type.generic-where-clause.intersection] When there are multiple functions in a trait that use the GAT, then the *intersection* of the bounds from the different functions are used, rather than the union. @@ -440,7 +439,7 @@ know that `T: 'a` on `create_checker`, we do not know that on `do_check`. Howeve if `do_check` was commented out, then the `where T: 'x` bound would be required on `Checker`. -r[items.associated.type.generic-where-clause.constraint-forward] +r[items.associated.type.generic-where-clause.forward] The bounds on associated types also propagate required where clauses. ```rust diff --git a/src/items/constant-items.md b/src/items/constant-items.md index 533345569..b80b145e7 100644 --- a/src/items/constant-items.md +++ b/src/items/constant-items.md @@ -11,7 +11,7 @@ r[items.const.intro] A *constant item* is an optionally named _[constant value]_ which is not associated with a specific memory location in the program. -r[items.const.behaviour] +r[items.const.behavior] Constants are essentially inlined wherever they are used, meaning that they are copied directly into the relevant context when used. This includes usage of constants from external crates, and non-[`Copy`] types. References to the same constant are not necessarily @@ -48,7 +48,7 @@ const BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings { }; ``` -r[items.const.restriction] +r[items.const.expr-omission] The constant expression may only be omitted in a [trait definition]. ## Constants with Destructors diff --git a/src/items/enumerations.md b/src/items/enumerations.md index d2441a1bf..f20c77d72 100644 --- a/src/items/enumerations.md +++ b/src/items/enumerations.md @@ -2,7 +2,7 @@ r[items.enum] -r[items.enum.sybtax] +r[items.enum.syntax] > **Syntax**\ > _Enumeration_ :\ >    `enum` @@ -128,7 +128,7 @@ let z = StructLike { value: 123 }; // Struct expression. r[items.enum.discriminant] -r[items.enum.discrimnant.intro] +r[items.enum.discriminant.intro] Each enum instance has a _discriminant_: an integer logically associated to it that is used to determine which variant it holds. @@ -150,7 +150,7 @@ following the variant name with `=` and a [constant expression]: r[items.enum.discriminant.explicit.unit-only] 1. if the enumeration is "[unit-only]". -r[items.enum.discriminan.explicit.primitive-repr] +r[items.enum.discriminant.explicit.primitive-repr] 2. if a [primitive representation] is used. For example: ```rust @@ -187,9 +187,9 @@ assert_eq!(baz_discriminant, 123); #### Restrictions -r[items.enum.discriminant.constraints] +r[items.enum.discriminant.restrictions] -r[items.enum.discrimnant.constraints.same-discriminant] +r[items.enum.discriminant.restrictions.same-discriminant] It is an error when two variants share the same discriminant. ```rust,compile_fail @@ -205,7 +205,7 @@ enum SharedDiscriminantError2 { } ``` -r[items.enum.discrimnant.constraints.above-max-discriminant] +r[items.enum.discriminant.restrictions.above-max-discriminant] It is also an error to have an unspecified discriminant where the previous discriminant is the maximum value for the size of the discriminant. @@ -254,7 +254,7 @@ assert_eq!(1, Enum::Bar as isize); assert_eq!(2, Enum::Baz as isize); ``` -r[items.enum.discriminant.coercion.constraint] +r[items.enum.discriminant.coercion.fieldless] [Field-less enums] can be casted if they do not have explicit discriminants, or where only unit variants are explicit. ```rust @@ -338,7 +338,7 @@ let y: u32 = x; // mismatched type error ## Variant visibility -r[items.enum.constraint-variant-visibility] +r[items.enum.variant-visibility] Enum variants syntactically allow a [_Visibility_] annotation, but this is rejected when the enum is validated. This allows items to be parsed with a diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index b0522934e..85f10630e 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -25,7 +25,7 @@ Additionally, if the `extern crate` appears in the crate root, then the crate na r[items.extern-crate.as] The `as` clause can be used to bind the imported crate to a different name. -r[items.exter-crate.lookup] +r[items.extern-crate.lookup] The external crate is resolved to a specific `soname` at compile time, and a runtime linkage requirement to that `soname` is passed to the linker for loading at runtime. The `soname` is resolved at compile time by scanning the diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 6cb49f03b..5839f242b 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -21,7 +21,7 @@ External blocks provide _declarations_ of items that are not _defined_ in the current crate and are the basis of Rust's foreign function interface. These are akin to unchecked imports. -r[items.extern.restriction] +r[items.extern.allowed-kinds] Two kinds of item _declarations_ are allowed in external blocks: [functions] and [statics]. @@ -38,10 +38,13 @@ r[items.extern.fn] r[items.extern.fn.body] Functions within external blocks are declared in the same way as other Rust functions, with the exception that they must not have a body and are instead -terminated by a semicolon +terminated by a semicolon. -r[items.extern.fn.restriction] -Patterns are not allowed in parameters, only [IDENTIFIER] or `_` may be used. The `safe` and `unsafe` function qualifiers are +r[items.extern.fn.param-patterns] +Patterns are not allowed in parameters, only [IDENTIFIER] or `_` may be used. + +r[items.extern.fn.qualifiers] +The `safe` and `unsafe` function qualifiers are allowed, but other function qualifiers (e.g. `const`, `async`, `extern`) are not. @@ -200,19 +203,19 @@ r[items.extern.attributes.link.raw-dylib] an import library to link against (see [`dylib` versus `raw-dylib`] below for details). This is only valid for Windows targets. -r[items.extern.attributes.link.constraint] +r[items.extern.attributes.link.name-requirement] The `name` key must be included if `kind` is specified. r[items.extern.attributes.link.modifiers] The optional `modifiers` argument is a way to specify linking modifiers for the library to link. -r[items.extern.attributes.link.modifiers-syntax] +r[items.extern.attributes.link.modifiers.syntax] Modifiers are specified as a comma-delimited string with each modifier prefixed with either a `+` or `-` to indicate that the modifier is enabled or disabled, respectively. -r[items.extern.attributes.link.modifiers-constraint] +r[items.extern.attributes.link.modifiers.multiple] Specifying multiple `modifiers` arguments in a single `link` attribute, or multiple identical modifiers in the same `modifiers` argument is not currently supported. \ Example: `#[link(name = "mylib", kind = "static", modifiers = "+whole-archive")]`. @@ -249,18 +252,18 @@ block. #### Linking modifiers: `bundle` -r[items.extern.attributes.link.modifier-bundle] +r[items.extern.attributes.link.modifiers.bundle] -r[items.extern.attributes.link.modifier-bundle.constraint] +r[items.extern.attributes.link.modifiers.bundle.allowed-kinds] This modifier is only compatible with the `static` linking kind. Using any other kind will result in a compiler error. -r[items.extern.attributes.link.modifier-bundle.behaviour] +r[items.extern.attributes.link.modifiers.bundle.behavior] When building a rlib or staticlib `+bundle` means that the native static library will be packed into the rlib or staticlib archive, and then retrieved from there during linking of the final binary. -r[items.extern.attributes.link.modifier-bundle.behaviour-negative] +r[items.extern.attributes.link.modifiers.bundle.behavior-negative] When building a rlib `-bundle` means that the native static library is registered as a dependency of that rlib "by name", and object files from it are included only during linking of the final binary, the file search by that name is also performed during final linking. \ @@ -268,10 +271,10 @@ When building a staticlib `-bundle` means that the native static library is simp into the archive and some higher level build system will need to add it later during linking of the final binary. -r[items.extern.attributes.link.modifier-bundle.no-effect] +r[items.extern.attributes.link.modifiers.bundle.no-effect] This modifier has no effect when building other targets like executables or dynamic libraries. -r[items.extern.attributes.link.modifier-bundle.default] +r[items.extern.attributes.link.modifiers.bundle.default] The default for this modifier is `+bundle`. More implementation details about this modifier can be found in @@ -279,17 +282,17 @@ More implementation details about this modifier can be found in #### Linking modifiers: `whole-archive` -r[items.extern.attributes.link.modifier-whole-archive] +r[items.extern.attributes.link.modifiers.whole-archive] -r[items.extern.attributes.link.modifier-whole-archive.constraint] +r[items.extern.attributes.link.modifiers.whole-archive.allowed-kinds] This modifier is only compatible with the `static` linking kind. Using any other kind will result in a compiler error. -r[items.extern.attributes.link.modifier-whole-archive.behaviour] +r[items.extern.attributes.link.modifiers.whole-archive.behavior] `+whole-archive` means that the static library is linked as a whole archive without throwing any object files away. -r[items.extern.attributes.link.modifier-whole-archive.default] +r[items.extern.attributes.link.modifiers.whole-archive.default] The default for this modifier is `-whole-archive`. More implementation details about this modifier can be found in @@ -297,21 +300,21 @@ More implementation details about this modifier can be found in ### Linking modifiers: `verbatim` -r[items.extern.attributes.link.modifier-verbatim] +r[items.extern.attributes.link.modifiers.verbatim] -r[items.extern.attributes.link.modifier-verbatim.constraint] +r[items.extern.attributes.link.modifiers.verbatim.allowed-kinds] This modifier is compatible with all linking kinds. -r[items.extern.attributes.link.modifier-verbatim.behaviour] +r[items.extern.attributes.link.modifiers.verbatim.behavior] `+verbatim` means that rustc itself won't add any target-specified library prefixes or suffixes (like `lib` or `.a`) to the library name, and will try its best to ask for the same thing from the linker. -r[items.extern.attributes.link.modifier-verbatim.behaviour-negative] +r[items.extern.attributes.link.modifiers.verbatim.behavior-negative] `-verbatim` means that rustc will either add a target-specific prefix and suffix to the library name before passing it to linker, or won't prevent linker from implicitly adding it. -r[items.extern.attributes.link.modifier-verbatim.default] +r[items.extern.attributes.link.modifiers.verbatim.default] The default for this modifier is `-verbatim`. More implementation details about this modifier can be found in @@ -420,7 +423,7 @@ unsafe extern "stdcall" { } ``` -r[items.extern.attributes.link_ordinal.constraints] +r[items.extern.attributes.link_ordinal.allowed-kinds] This attribute is only used with the `raw-dylib` linking kind. Using any other kind will result in a compiler error. diff --git a/src/items/functions.md b/src/items/functions.md index 3b258d12d..8300ad19d 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -75,7 +75,7 @@ fn answer_to_life_the_universe_and_everything() -> i32 { } ``` -r[items.fn.constraint-safety-qualifiers] +r[items.fn.safety-qualifiers] The `safe` function is semantically only allowed when used in an [`extern` block]. ## Function parameters @@ -94,7 +94,7 @@ r[items.fn.params.self-pat] If the first parameter is a _SelfParam_, this indicates that the function is a [method]. -r[items.fn.params.self-constraint] +r[items.fn.params.self-restriction] Functions with a self parameter may only appear as an [associated function] in a [trait] or [implementation]. @@ -125,7 +125,7 @@ return { }; ``` -r[items.fn.body.restriction] +r[items.fn.body.bodyless] Functions without a body block are terminated with a semicolon. This form may only appear in a [trait] or [external block]. @@ -271,7 +271,7 @@ Functions qualified with the `const` keyword are [const functions], as are [tuple struct] and [tuple variant] constructors. _Const functions_ can be called from within [const contexts]. -r[item.fn.const.extern] +r[items.fn.const.extern] Const functions may use the [`extern`] function qualifier. r[items.fn.const.exclusivity] @@ -320,7 +320,7 @@ fn example<'a>(x: &'a str) -> impl Future + 'a { r[items.fn.async.desugar] The actual desugaring is more complex: -r[items.fn.async.lifetime-catpure] +r[items.fn.async.lifetime-capture] - The return type in the desugaring is assumed to capture all lifetime parameters from the `async fn` declaration. This can be seen in the desugared example above, which explicitly outlives, and hence @@ -373,7 +373,6 @@ async fn safe_example() { } ``` -r[items.fn.async.safety.] Note that this behavior is a consequence of the desugaring to a function that returns an `impl Future` -- in this case, the function we desugar to is an `unsafe` function, but the return value remains diff --git a/src/items/generics.md b/src/items/generics.md index 498de7424..feb84ee69 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -30,7 +30,7 @@ implementations, which don't have a name, they come directly after `impl`. r[items.generics.syntax.decl-order] The order of generic parameters is restricted to lifetime parameters and then type and const parameters intermixed. -r[items.generics.syntax.constraint] +r[items.generics.syntax.duplicate-params] The same parameter name may not be declared more than once in a _GenericParams_ list. Some examples of items with type, const, and lifetime parameters: @@ -54,7 +54,7 @@ r[items.generics.builtin-generic-types] [function pointers] have lifetime or type parameters as well, but are not referred to with path syntax. -r[items.generics.constraint-widlcard-lifetime] +r[items.generics.wildcard-lifetime] `'_` is not a valid lifetime parameter. ### Const generics @@ -67,7 +67,7 @@ r[items.generics.const.intro] r[items.generics.const.namespace] The const identifier introduces a name in the [value namespace] for the constant parameter, and all instances of the item must be instantiated with a value of the given type. -r[items.generics.const.constraint] +r[items.generics.const.allowed-types] The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128`, `usize`, `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `char` and `bool`. @@ -129,7 +129,7 @@ fn foo() { } ``` -r[items.generics.const.constraint-const-expr] +r[items.generics.const.standalone] As a further restriction, const parameters may only appear as a standalone argument inside of a [type] or [array repeat expression]. In those contexts, they may only be used as a single segment [path expression], possibly inside a @@ -150,7 +150,7 @@ fn bad_function() -> [u8; {N + 1}] { r[items.generics.const.argument] A const argument in a [path] specifies the const value to use for that item. -r[items.generics.const.argument-restriction] +r[items.generics.const.argument.const-expr] The argument must be a [const expression] of the type ascribed to the const parameter. The const expression must be a [block expression][block] (surrounded with braces) unless it is a single path segment (an [IDENTIFIER]) @@ -256,7 +256,7 @@ r[items.generics.where.intro] parameters as well as a way to specify bounds on types that aren't type parameters. -r[items.generics.where.higher-ranked-;ifetimes] +r[items.generics.where.higher-ranked-lifetimes] The `for` keyword can be used to introduce [higher-ranked lifetimes]. It only allows [_LifetimeParam_] parameters. diff --git a/src/items/implementations.md b/src/items/implementations.md index 6f631f3c2..5bde1ec21 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -51,10 +51,10 @@ r[items.impl.inherent.associated-items] Inherent implementations associate the contained items to the implementing type. -r[items.impl.inherent.values] +r[items.impl.inherent.associated-items.allowed-items] Inherent implementations can contain [associated functions] (including [methods]) and [associated constants]. -r[items.impl.inherent.constraint-type-alias] +r[items.impl.inherent.type-alias] They cannot contain associated type aliases. r[items.impl.inherent.associated-item-path] @@ -115,7 +115,7 @@ r[items.impl.trait.implemented-trait] The trait is known as the _implemented trait_. The implementing type implements the implemented trait. -r[items.impl.trait.constraint] +r[items.impl.trait.def-requirement] A trait implementation must define all non-default associated items declared by the implemented trait, may redefine default associated items defined by the implemented trait, and cannot define any other items. @@ -226,7 +226,7 @@ least once in one of: * As an [associated type] in the [bounds] of a type that contains another parameter that constrains the implementation -r[items.impl.generics.constraint] +r[items.impl.generics.constrain] Type and const parameters must always constrain the implementation. Lifetimes must constrain the implementation if the lifetime is used in an associated type. diff --git a/src/items/modules.md b/src/items/modules.md index 3244aad13..c8fd4c89e 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -45,11 +45,11 @@ mod math { r[items.mod.namespace] Modules are defined in the [type namespace] of the module or block where they are located. -r[items.mod.namespace-def] +r[items.mod.multiple-items] It is an error to define multiple items with the same name in the same namespace within a module. See the [scopes chapter] for more details on restrictions and shadowing behavior. -r[items.mod.constraint] +r[items.mod.unsafe] The `unsafe` keyword is syntactically allowed to appear before the `mod` keyword, but it is rejected at a semantic level. This allows macros to consume the syntax and make use of the `unsafe` keyword, before removing it from the diff --git a/src/items/static-items.md b/src/items/static-items.md index 55890712e..f7e47736c 100644 --- a/src/items/static-items.md +++ b/src/items/static-items.md @@ -36,17 +36,17 @@ r[items.static.safety] All access to a static is safe, but there are a number of restrictions on statics: -r[items.static.constraint-sync] +r[items.static.sync] * The type must have the `Sync` trait bound to allow thread-safe access. -r[items.static.constraint-const] +r[items.static.const] * Constants cannot refer to statics. -r[items.static.restriction-init] +r[items.static.init.omission] The initializer expression must be omitted in an [external block], and must be provided for free static items. -r[items.static.constraint-safety-qualifier] +r[items.static.safety-qualifiers] The `safe` and `unsafe` qualifiers are semantically only allowed when used in an [external block]. ## Statics & generics @@ -147,7 +147,7 @@ fn bump_levels_safe() -> u32 { } ``` -r[items.static.mut.constraints] +r[items.static.mut.sync] Mutable statics have the same restrictions as normal statics, except that the type does not have to implement the `Sync` trait. diff --git a/src/items/traits.md b/src/items/traits.md index a16ad0172..dd315e440 100644 --- a/src/items/traits.md +++ b/src/items/traits.md @@ -1,8 +1,8 @@ # Traits -r[items.trait] +r[items.traits] -r[items.trait.syntax] +r[items.traits.syntax] > **Syntax**\ > _Trait_ :\ >    `unsafe`? `trait` [IDENTIFIER]  @@ -13,7 +13,7 @@ r[items.trait.syntax] >      [_AssociatedItem_]\*\ >    `}` -r[items.trait.intro] +r[items.traits.intro] A _trait_ describes an abstract interface that types can implement. This interface consists of [associated items], which come in three varieties: @@ -21,22 +21,22 @@ interface consists of [associated items], which come in three varieties: - [types](associated-items.md#associated-types) - [constants](associated-items.md#associated-constants) -r[items.trait.namespace] +r[items.traits.namespace] The trait declaration defines a trait in the [type namespace] of the module or block where it is located. -r[items.trait.associated-item-namespaces] +r[items.traits.associated-item-namespaces] Associated items are defined as members of the trait within their respective namespaces. Associated types are defined in the type namespace. Associated constants and associated functions are defined in the value namespace. -r[items.trait.self-param] +r[items.traits.self-param] All traits define an implicit type parameter `Self` that refers to "the type that is implementing this interface". Traits may also contain additional type parameters. These type parameters, including `Self`, may be constrained by other traits and so forth [as usual][generics]. -r[items.trait.impls] +r[items.traits.impls] Traits are implemented for specific types through separate [implementations]. -r[items.trait.associated-item-decls] +r[items.traits.associated-item-decls] Trait functions may omit the function body by replacing it with a semicolon. This indicates that the implementation must define the function. If the trait function defines a body, this definition acts as a default for any @@ -56,7 +56,7 @@ trait Example { } ``` -r[items.trait.fn-constraint] +r[items.traits.const-fn] Trait functions are not allowed to be [`const`]. ## Trait bounds @@ -83,25 +83,25 @@ trait Seq { ## Dyn compatibility -r[items.trait.dyn-compatible] +r[items.traits.dyn-compatible] -r[items.trait.dyn-compatible.intro] +r[items.traits.dyn-compatible.intro] A dyn-compatible trait can be the base trait of a [trait object]. A trait is *dyn compatible* if it has the following qualities: -r[items.trait.dyn-compatible.supertraits] +r[items.traits.dyn-compatible.supertraits] * All [supertraits] must also be dyn compatible. -r[items.trait.dyn-compatible.sized] +r[items.traits.dyn-compatible.sized] * `Sized` must not be a [supertrait][supertraits]. In other words, it must not require `Self: Sized`. -r[items.trait.dyn-compatible.associated-consts] +r[items.traits.dyn-compatible.associated-consts] * It must not have any associated constants. -r[items.trait.dyn-compatible.associated-types] +r[items.traits.dyn-compatible.associated-types] * It must not have any associated types with generics. -r[items.trait.dyn-compatible.associated-functions] +r[items.traits.dyn-compatible.associated-functions] * All associated functions must either be dispatchable from a trait object or be explicitly non-dispatchable: * Dispatchable functions must: * Not have any type parameters (although lifetime parameters are allowed). @@ -206,19 +206,19 @@ let obj: Box = Box::new(S); // ERROR: cannot use `Self` type param ## Supertraits -r[items.trait.supertraits] +r[items.traits.supertraits] -r[items.trait.supertraits.intro] +r[items.traits.supertraits.intro] **Supertraits** are traits that are required to be implemented for a type to implement a specific trait. Furthermore, anywhere a [generic][generics] or [trait object] is bounded by a trait, it has access to the associated items of its supertraits. -r[items.trait.supertraits.decl] +r[items.traits.supertraits.decl] Supertraits are declared by trait bounds on the `Self` type of a trait and transitively the supertraits of the traits declared in those trait bounds. It is an error for a trait to be its own supertrait. -r[items.trait.supertraits.subtrait] +r[items.traits.supertraits.subtrait] The trait with a supertrait is called a **subtrait** of its supertrait. The following is an example of declaring `Shape` to be a supertrait of `Circle`. @@ -277,9 +277,9 @@ let nonsense = circle.radius() * circle.area(); ## Unsafe traits -r[items.trait.safety] +r[items.traits.safety] -r[items.trait.safety.intro] +r[items.traits.safety.intro] Traits items that begin with the `unsafe` keyword indicate that *implementing* the trait may be [unsafe]. It is safe to use a correctly implemented unsafe trait. The [trait implementation] must also begin with the `unsafe` keyword. @@ -288,15 +288,15 @@ The [trait implementation] must also begin with the `unsafe` keyword. ## Parameter patterns -r[items.trait.params] +r[items.traits.params] -r[items.trait.params.constraint] +r[items.traits.params.allowed-patterns] Function or method declarations without a body only allow [IDENTIFIER] or `_` [wild card][WildcardPattern] patterns. `mut` [IDENTIFIER] is currently allowed, but it is deprecated and will become a hard error in the future. -r[items.trait.params.edition2015] +r[items.traits.params.edition2015] In the 2015 edition, the pattern for a trait function or method parameter is optional: @@ -307,7 +307,7 @@ trait T { } ``` -r[items.trait.params.restriction] +r[items.traits.params.restriction] The kinds of patterns for parameters is limited to one of the following: * [IDENTIFIER] @@ -316,7 +316,7 @@ The kinds of patterns for parameters is limited to one of the following: * `&` [IDENTIFIER] * `&&` [IDENTIFIER] -r[items.trait.params.restriction-edition2018] +r[items.traits.params.restriction.edition2018] Beginning in the 2018 edition, function or method parameter patterns are no longer optional. Also, all irrefutable patterns are allowed as long as there is a body. Without a body, the limitations listed above are still in effect. @@ -330,9 +330,9 @@ trait T { ## Item visibility -r[items.trait.associated-visibility] +r[items.traits.associated-visibility] -r[items.trait.associated-visibility.intro] +r[items.traits.associated-visibility.intro] Trait items syntactically allow a [_Visibility_] annotation, but this is rejected when the trait is validated. This allows items to be parsed with a unified syntax across different contexts where they are used. As an example, diff --git a/src/items/type-aliases.md b/src/items/type-aliases.md index 434639589..d496b8c60 100644 --- a/src/items/type-aliases.md +++ b/src/items/type-aliases.md @@ -22,7 +22,7 @@ type Point = (u8, u8); let p: Point = (41, 68); ``` -r[items.type.constraint-constructor] +r[items.type.constructor-alias] A type alias to a tuple-struct or unit-struct cannot be used to qualify that type's constructor: ```rust,compile_fail @@ -35,15 +35,15 @@ let _ = UseAlias(5); // OK let _ = TypeAlias(5); // Doesn't work ``` -r[items.type.constraint] +r[items.type.associated-type] A type alias, when not used as an [associated type], must include a [_Type_] and may not include [_TypeParamBounds_]. -r[items.type.constraint-associated-trait] +r[items.type.associated-trait] A type alias, when used as an [associated type] in a [trait], must not include a [_Type_] specification but may include [_TypeParamBounds_]. -r[items.type.constraint-associated-impl] +r[items.type.associated-impl] A type alias, when used as an [associated type] in a [trait impl], must include a [_Type_] specification and may not include [_TypeParamBounds_]. diff --git a/src/items/unions.md b/src/items/unions.md index f1e696a08..835f924ea 100644 --- a/src/items/unions.md +++ b/src/items/unions.md @@ -28,7 +28,7 @@ The key property of unions is that all fields of a union share common storage. As a result, writes to one field of a union can overwrite its other fields, and size of a union is determined by the size of its largest field. -r[items.union.field-constraints] +r[items.union.field-restrictions] Union field types are restricted to the following subset of types: r[items.union.field-copy] @@ -48,7 +48,7 @@ This restriction ensures, in particular, that union fields never need to be dropped. Like for structs and enums, it is possible to `impl Drop` for a union to manually define what happens when it gets dropped. -r[items.union.constraint] +r[items.union.fieldless] Unions without any fields are not accepted by the compiler, but can be accepted by macros. ## Initialization of a union @@ -92,7 +92,7 @@ r[items.union.fields.offset] Fields might have a non-zero offset (except when [the C representation] is used); in that case the bits starting at the offset of the fields are read -r[items.union.fields.precondition] +r[items.union.fields.validity] It is the programmer's responsibility to make sure that the data is valid at the field's type. Failing to do so results in [undefined behavior]. For example, reading the value `3` from a field of the [boolean type] is undefined behavior. Effectively, @@ -128,7 +128,7 @@ r[items.union.pattern] r[items.union.pattern.intro] Another way to access union fields is to use pattern matching. -r[items.union.pattern.constraint] +r[items.union.pattern.one-field] Pattern matching on union fields uses the same syntax as struct patterns, except that the pattern must specify exactly one field. diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index c66f07352..ca70b8a8b 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -23,27 +23,27 @@ A `use` declaration is also sometimes called an _import_, or, if it is public, a [modules]: modules.md [blocks]: ../expressions/block-expr.md -r[items.use.modes] +r[items.use.forms] Use declarations support a number of convenient shortcuts: -r[items.use.mode-multiple] +r[items.use.forms.multiple] * Simultaneously binding a list of paths with a common prefix, using the brace syntax `use a::b::{c, d, e::f, g::h::i};` -r[items.use.mode-self] +r[items.use.forms.self] * Simultaneously binding a list of paths with a common prefix and their common parent module, using the `self` keyword, such as `use a::b::{self, c, d::e};` -r[items.use.mode-as] +r[items.use.forms.as] * Rebinding the target name as a new local name, using the syntax `use p::q::r as x;`. This can also be used with the last two features: `use a::b::{self as ab, c as abc}`. -r[items.use.mode-glob] +r[items.use.forms.glob] * Binding all paths matching a given prefix, using the asterisk wildcard syntax `use a::b::*;`. -r[items.use.mode-nesting] +r[items.use.forms.nesting] * Nesting groups of the previous features multiple times, such as `use a::b::{self as ab, c, d::{*, e::f}};` @@ -72,7 +72,7 @@ fn main() { ## `use` Visibility -r[items.use.vis] +r[items.use.visibility] r[items.use.visibility.intro] Like items, `use` declarations are private to the containing module, by @@ -82,7 +82,7 @@ public `use` declaration can therefore _redirect_ some public name to a different target definition: even a definition with a private canonical path, inside a different module. -r[items.use.visibility.constraint] +r[items.use.visibility.unambiguous] If a sequence of such redirections form a cycle or cannot be resolved unambiguously, they represent a compile-time error. @@ -120,7 +120,7 @@ They may create bindings for: * [Attributes] * [Derive macros] -r[items.use.path.constraint] +r[items.use.path.disallowed] They cannot import [associated items], [generic parameters], [local variables], paths with [`Self`], or [tool attributes]. More restrictions are described below. r[items.use.path.namespace] @@ -197,7 +197,7 @@ Braces can be nested, creating a tree of paths, where each grouping of segments use std::collections::{BTreeSet, hash_map::{self, HashMap}}; ``` -r[items.use.multiple-syntax.sempty] +r[items.use.multiple-syntax.empty] An empty brace does not import anything, though the leading path is validated that it is accessible. @@ -309,8 +309,10 @@ mod clashing { } ``` -r[items.use.glob.restriction] +r[items.use.glob.last-segment-only] `*` cannot be used as the first or intermediate segments. + +r[items.use.glob.self-import] `*` cannot be used to import a module's contents into itself (such as `use self::*;`). r[items.use.glob.edition2015] @@ -368,23 +370,23 @@ m!(use std as _;); ## Restrictions -r[items.use.restriction] +r[items.use.restrictions] The following are restrictions for valid `use` declarations: -r[items.use.restriction.crate] +r[items.use.restrictions.crate] * `use crate;` must use `as` to define the name to which to bind the crate root. -r[items.use.restriction.self] +r[items.use.restrictions.self] * `use {self};` is an error; there must be a leading segment when using `self`. -r[items.use.restriction.duplicate-name] +r[items.use.restrictions.duplicate-name] * As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block. -r[items.use.restriction.macro-crate] +r[items.use.restrictions.macro-crate] * `use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. -r[items.use.restriction.variant] +r[items.use.restrictions.variant] * `use` paths cannot refer to enum variants through a [type alias]. For example: ```rust,compile_fail enum MyEnum { @@ -398,14 +400,14 @@ r[items.use.restriction.variant] ## Ambiguities -r[items.use.ambiguity] +r[items.use.ambiguities] > **Note**: This section is incomplete. -r[items.use.ambiguity.intro] +r[items.use.ambiguities.intro] Some situations are an error when there is an ambiguity as to which name a `use` declaration refers. This happens when there are two name candidates that do not resolve to the same entity. -r[items.use.ambiguity.glob] +r[items.use.ambiguities.glob] Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used. For example: