Merge branch 'master' into spec-add-identifiers-rest

docs/authoring.md

@@ -154,4 +154,4 @@ The reference does not document which targets exist, or the properties of specif
 
 ### Editions
 
-The main text and flow should document only the current edition. Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block.
+The main text and flow should document only the current edition. Whenever there is a difference between editions, the differences should be called out with an "Edition differences" block.

mdbook-spec/src/lib.rs

@@ -1,3 +1,5 @@
+#![deny(rust_2018_idioms, unused_lifetimes)]
+
 use mdbook::book::{Book, Chapter};
 use mdbook::errors::Error;
 use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext};
@@ -82,8 +84,8 @@ impl Spec {
                     }
                 }
                 format!(
-                    "<div class=\"rule\" id=\"{rule_id}\">\
-                     <a class=\"rule-link\" href=\"#{rule_id}\">[{rule_id}]</a>\
+                    "<div class=\"rule\" id=\"r-{rule_id}\">\
+                     <a class=\"rule-link\" href=\"#r-{rule_id}\">[{rule_id}]</a>\
                      </div>\n"
                 )
             })
@@ -102,7 +104,7 @@ impl Spec {
             .iter()
             .map(|(rule_id, (_, path))| {
                 let relative = pathdiff::diff_paths(path, current_path).unwrap();
-                format!("[{rule_id}]: {}#{rule_id}\n", relative.display())
+                format!("[{rule_id}]: {}#r-{rule_id}\n", relative.display())
             })
             .collect();
         format!(

mdbook-spec/src/std_links.rs

@@ -145,7 +145,7 @@ fn collect_markdown_links(chapter: &Chapter) -> Vec<Link<'_>> {
     // Broken links are collected so that you can write something like
     // `[std::option::Option]` which in pulldown_cmark's eyes is a broken
     // link. However, that is the normal syntax for rustdoc.
-    let broken_link = |broken_link: BrokenLink| {
+    let broken_link = |broken_link: BrokenLink<'_>| {
         broken_links.push(Link {
             link_type: broken_link.link_type,
             // Necessary due to lifetime issues.
@@ -205,7 +205,7 @@ fn collect_markdown_links(chapter: &Chapter) -> Vec<Link<'_>> {
 /// generate intra-doc links on them.
 ///
 /// The output will be in the given `tmp` directory.
-fn run_rustdoc(tmp: &TempDir, chapter_links: &HashMap<&PathBuf, Vec<Link>>) {
+fn run_rustdoc(tmp: &TempDir, chapter_links: &HashMap<&PathBuf, Vec<Link<'_>>>) {
     let src_path = tmp.path().join("a.rs");
     // Allow redundant since there could some in-scope things that are
     // technically not necessary, but we don't care about (like

src/const_eval.md

@@ -61,40 +61,24 @@ A _const context_ is one of the following:
 * A [const generic argument]
 * A [const block]
 
+Const contexts that are used as parts of types (array type and repeat length
+expressions as well as const generic arguments) can only make restricted use of
+surrounding generic parameters: such an expression must either be a single bare
+const generic parameter, or an arbitrary expression not making use of any
+generics.
+
 ## Const Functions
 
 A _const fn_ is a function that one is permitted to call from a const context. Declaring a function
 `const` has no effect on any existing uses, it only restricts the types that arguments and the
-return type may use, as well as prevent various expressions from being used within it. You can freely
-do anything with a const function that you can do with a regular function.
+return type may use, and restricts the function body to constant expressions.
 
 When called from a const context, the function is interpreted by the
 compiler at compile time. The interpretation happens in the
 environment of the compilation target and not the host. So `usize` is
 `32` bits if you are compiling against a `32` bit system, irrelevant
 of whether you are building on a `64` bit or a `32` bit system.
 
-Const functions have various restrictions to make sure that they can be
-evaluated at compile-time. It is, for example, not possible to write a random
-number generator as a const function. Calling a const function at compile-time
-will always yield the same result as calling it at runtime, even when called
-multiple times. There's one exception to this rule: if you are doing complex
-floating point operations in extreme situations, then you might get (very
-slightly) different results. It is advisable to not make array lengths and enum
-discriminants depend on floating point computations.
-
-
-Notable features that are allowed in const contexts but not in const functions include:
-
-* floating point operations
-  * floating point values are treated just like generic parameters without trait bounds beyond
-  `Copy`. So you cannot do anything with them but copy/move them around.
-
-Conversely, the following are possible in a const function, but not in a const context:
-
-* Use of generic type and lifetime parameters.
-  * Const contexts do allow limited use of [const generic parameters].
-
 [arithmetic]:           expressions/operator-expr.md#arithmetic-and-logical-binary-operators
 [array expressions]:    expressions/array-expr.md
 [array indexing]:       expressions/array-expr.md#array-and-slice-indexing-expressions

src/expressions/method-call-expr.md

@@ -66,7 +66,7 @@ Once a method is looked up, if it can't be called for one (or more) of those rea
 If a step is reached where there is more than one possible method, such as where generic methods or traits are considered the same, then it is a compiler error.
 These cases require a [disambiguating function call syntax] for method and function invocation.
 
-> **Edition Differences**: Before the 2021 edition, during the search for visible methods, if the candidate receiver type is an [array type], methods provided by the standard library [`IntoIterator`] trait are ignored.
+> **Edition differences**: Before the 2021 edition, during the search for visible methods, if the candidate receiver type is an [array type], methods provided by the standard library [`IntoIterator`] trait are ignored.
 >
 > The edition used for this purpose is determined by the token representing the method name.
 >

src/introduction.md

@@ -82,9 +82,9 @@ These conventions are documented here.
 
   An *example term* is an example of a term being defined.
 
-* Differences in the language by which edition the crate is compiled under are in a blockquote that start with the words "Edition Differences:" in **bold**.
+* Differences in the language by which edition the crate is compiled under are in a blockquote that start with the words "Edition differences:" in **bold**.
 
-  > **Edition Differences**: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition.
+  > **Edition differences**: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition.
 
 * Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in blockquotes that start with the word "Note:" in **bold**.
 
@@ -120,6 +120,15 @@ These conventions are documented here.
 
   See [Notation] for more detail.
 
+* Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to a specific rule in the language. The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example).
+
+  The rule name can be clicked to link to that rule.
+
+r[example.rule.label]
+
+  > [!WARNING]
+  > The organization of the rules is currently in flux. For the time being, these identifier names are not stable between releases, and links to these rules may fail if they are changed. We intend to stabilize these once the organization has settled so that links to the rule names will not break between releases.
+
 ## Contributing
 
 We welcome contributions of all kinds.

src/items/associated-items.md

@@ -189,7 +189,7 @@ let circle_shape = Circle::new();
 let bounding_box = circle_shape.bounding_box();
 ```
 
-> **Edition Differences**: In the 2015 edition, it is possible to declare trait
+> **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.
 

src/macros-by-example.md

@@ -148,7 +148,7 @@ the `expr` fragment specifier. However, `_` is matched by the `expr` fragment
 specifier when it appears as a subexpression.
 For the same reason, a standalone [const block] is not matched but it is matched when appearing as a subexpression.
 
-> **Edition Differences**: Starting with the 2021 edition, `pat` fragment-specifiers match top-level or-patterns (that is, they accept [_Pattern_]).
+> **Edition differences**: Starting with the 2021 edition, `pat` fragment-specifiers match top-level or-patterns (that is, they accept [_Pattern_]).
 >
 > Before the 2021 edition, they match exactly the same fragments as `pat_param` (that is, they accept [_PatternNoTopAlt_]).
 >
@@ -421,7 +421,7 @@ macro_rules! call_foo {
 fn foo() {}
 ```
 
-> **Version & Edition Differences**: Prior to Rust 1.30, `$crate` and
+> **Version & Edition differences**: Prior to Rust 1.30, `$crate` and
 > `local_inner_macros` (below) were unsupported. They were added alongside
 > path-based imports of macros (described above), to ensure that helper macros
 > did not need to be manually imported by users of a macro-exporting crate.
@@ -475,7 +475,7 @@ Matchers like `$i:expr,` or `$i:expr;` would be legal, however, because `,` and
     `ident`, `ty`, or `path` fragment specifier.
   * All other fragment specifiers have no restrictions.
 
-> **Edition Differences**: Before the 2021 edition, `pat` may also be followed by `|`.
+> **Edition differences**: Before the 2021 edition, `pat` may also be followed by `|`.
 
 When repetitions are involved, then the rules apply to every possible number of
 expansions, taking separators into account. This means:

src/names/preludes.md

@@ -44,7 +44,7 @@ new_name`, then the symbol `new_name` is instead added to the prelude.
 The [`core`] crate is always added to the extern prelude. The [`std`] crate is
 added as long as the [`no_std` attribute] is not specified in the crate root.
 
-> **Edition Differences**: In the 2015 edition, crates in the extern prelude
+> **Edition differences**: In the 2015 edition, crates in the extern prelude
 > cannot be referenced via [use declarations], so it is generally standard
 > practice to include `extern crate` declarations to bring them into scope.
 >
@@ -132,7 +132,7 @@ module or any of its descendants.
 
 This attribute does not affect the [language prelude].
 
-> **Edition Differences**: In the 2015 edition, the `no_implicit_prelude`
+> **Edition differences**: In the 2015 edition, the `no_implicit_prelude`
 > attribute does not affect the [`macro_use` prelude], and all macros exported
 > from the standard library are still included in the `macro_use` prelude.
 > Starting in the 2018 edition, it will remove the `macro_use` prelude.

src/paths.md

@@ -195,6 +195,7 @@ Paths starting with `::` are considered to be *global paths* where the segments
 start being resolved from a place which differs based on edition. Each identifier in
 the path must resolve to an item.
 
+
 r[path.qualifier.global-root.edition2015]
 > **Edition Differences**: In the 2015 Edition, identifiers resolve from the "crate root"
 > (`crate::` in the 2018 edition), which contains a variety of different items, including

src/patterns.md

@@ -645,7 +645,7 @@ The range of values for an integer type is the closed range from its minimum to
 r[pattern.range.refutable-char]
 The range of values for a `char` type are precisely those ranges containing all Unicode Scalar Values: `'\u{0000}'..='\u{D7FF}'` and `'\u{E000}'..='\u{10FFFF}'`.
 
-> **Edition Differences**: Before the 2021 edition, range patterns with both a lower and upper bound may also be written using `...` in place of `..=`, with the same meaning.
+> **Edition differences**: Before the 2021 edition, range patterns with both a lower and upper bound may also be written using `...` in place of `..=`, with the same meaning.
 
 ## Reference patterns
 

src/tokens.md

@@ -375,7 +375,7 @@ c"\u{00E6}";
 c"\xC3\xA6";
 ```
 
-> **Edition Differences**: C string literals are accepted in the 2021 edition or
+> **Edition differences**: C string literals are accepted in the 2021 edition or
 > later. In earlier additions the token `c""` is lexed as `c ""`.
 
 #### Raw C string literals
@@ -400,7 +400,7 @@ encoding. The characters `U+0022` (double-quote) (except when followed by at
 least as many `U+0023` (`#`) characters as were used to start the raw C string
 literal) or `U+005C` (`\`) do not have any special meaning.
 
-> **Edition Differences**: Raw C string literals are accepted in the 2021
+> **Edition differences**: Raw C string literals are accepted in the 2021
 > edition or later. In earlier additions the token `cr""` is lexed as `cr ""`,
 > and `cr#""#` is lexed as `cr #""#` (which is non-grammatical).
 
@@ -735,7 +735,7 @@ Note that raw identifiers, raw string literals, and raw byte string literals may
 
 Similarly the `r`, `b`, `br`, `c`, and `cr` prefixes used in raw string literals, byte literals, byte string literals, raw byte string literals, C string literals, and raw C string literals are not interpreted as reserved prefixes.
 
-> **Edition Differences**: Starting with the 2021 edition, reserved prefixes are reported as an error by the lexer (in particular, they cannot be passed to macros).
+> **Edition differences**: Starting with the 2021 edition, reserved prefixes are reported as an error by the lexer (in particular, they cannot be passed to macros).
 >
 > Before the 2021 edition, reserved prefixes are accepted by the lexer and interpreted as multiple tokens (for example, one token for the identifier or keyword, followed by a `#` token).
 >

src/types/enum.md

@@ -16,7 +16,7 @@ Enum types cannot be denoted *structurally* as types, but must be denoted by
 named reference to an [`enum` item].
 
 [^enumtype]: The `enum` type is analogous to a `data` constructor declaration in
-             ML, or a *pick ADT* in Limbo.
+             Haskell, or a *pick ADT* in Limbo.
 
 [`enum` item]: ../items/enumerations.md
 [struct expression]: ../expressions/struct-expr.md

src/types/trait-object.md

@@ -31,13 +31,13 @@ For example, given a trait `Trait`, the following are all trait objects:
 * `dyn 'static + Trait`.
 * `dyn (Trait)`
 
-> **Edition Differences**: Before the 2021 edition, the `dyn` keyword may be
+> **Edition differences**: Before the 2021 edition, the `dyn` keyword may be
 > omitted.
 >
 > Note: For clarity, it is recommended to always use the `dyn` keyword on your
 > trait objects unless your codebase supports compiling with Rust 1.26 or lower.
 
-> **Edition Differences**: In the 2015 edition, if the first bound of the
+> **Edition differences**: In the 2015 edition, if the first bound of the
 > trait object is a path that starts with `::`, then the `dyn` will be treated
 > as a part of the path. The first path can be put in parenthesis to get
 > around this. As such, if you want a trait object with the trait

src/visibility-and-privacy.md

@@ -156,7 +156,7 @@ follows:
 - `pub(self)` makes an item visible to the current module. This is equivalent
 to `pub(in self)` or not using `pub` at all.
 
-> **Edition Differences**: Starting with the 2018 edition, paths for
+> **Edition differences**: Starting with the 2018 edition, paths for
 > `pub(in path)` must start with `crate`, `self`, or `super`. The 2015 edition
 > may also use paths starting with `::` or modules from the crate root.