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.

Author: ehuss

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]

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<S> | Rc<S> | Arc<S> | Pin<P>
 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.
@@ -215,7 +214,7 @@ 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.
@@ -234,7 +233,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.
 
@@ -257,9 +256,9 @@ type Assoc<Params>: 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]
@@ -269,7 +268,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`:
 
 <!-- ignore: illustrative example forms -->
@@ -406,7 +405,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)
@@ -423,7 +422,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.
@@ -441,7 +440,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

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
@@ -49,7 +49,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

src/items/enumerations.md

@@ -2,7 +2,7 @@
 
 r[items.enum]
 
-r[items.enum.sybtax]
+r[items.enum.syntax]
 > **<sup>Syntax</sup>**\
 > _Enumeration_ :\
 > &nbsp;&nbsp; `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

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

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.
 
@@ -199,19 +202,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")]`.
@@ -248,69 +251,69 @@ 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. \
 When building a staticlib `-bundle` means that the native static library is simply not included
 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
 [`bundle` documentation for rustc].
 
 #### 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
 [`whole-archive` documentation for rustc].
 
 ### 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
@@ -425,7 +428,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.