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

Author: chorman0773

docs/authoring.md

@@ -15,7 +15,8 @@ This document serves as a guide for editors and reviewers. Some conventions and
 * Code blocks should have an explicit language tag.
 * Do not wrap long lines. This helps with reviewing diffs of the source.
 * Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters.
-* Links should be relative with the `.md` extension. Links to other rust-lang books that are published with the reference or the standard library API should also be relative so that the linkchecker can validate them.
+* Links should be relative with the `.md` extension. Links to other rust-lang books that are published with the reference should also be relative so that the linkchecker can validate them.
+* Links to the standard library should use rustdoc-style links described in [Standard library links](#standard-library-links).
 * The use of reference links is preferred, with shortcuts if appropriate. Place the sorted link reference definitions at the bottom of the file, or at the bottom of a section if there are an unusually large number of links that are specific to the section.
 
     ```markdown
@@ -154,4 +155,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};
@@ -17,7 +19,7 @@ static RULE_RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"(?m)^r\[([^]]+)]$").unwr
 /// The Regex for the syntax for blockquotes that have a specific CSS class,
 /// like `> [!WARNING]`.
 static ADMONITION_RE: Lazy<Regex> = Lazy::new(|| {
-    Regex::new(r"(?m)^ *> \[!(?<admon>[^]]+)\]\n(?<blockquote>(?: *> .*\n)+)").unwrap()
+    Regex::new(r"(?m)^ *> \[!(?<admon>[^]]+)\]\n(?<blockquote>(?: *>.*\n)+)").unwrap()
 });
 
 pub fn handle_preprocessing(pre: &dyn Preprocessor) -> Result<(), Error> {
@@ -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!(
@@ -129,15 +131,30 @@ impl Spec {
         ADMONITION_RE
             .replace_all(&chapter.content, |caps: &Captures<'_>| {
                 let lower = caps["admon"].to_lowercase();
+                let term = to_initial_case(&caps["admon"]);
+                let blockquote = &caps["blockquote"];
+                let initial_spaces = blockquote.chars().position(|ch| ch != ' ').unwrap_or(0);
+                let space = &blockquote[..initial_spaces];
                 format!(
-                    "<div class=\"{lower}\">\n\n{}\n\n</div>\n",
-                    &caps["blockquote"]
+                    "{space}<div class=\"{lower}\">\n\
+                    \n\
+                    {space}> ***{term}:***\n\
+                    {blockquote}\n\
+                    \n\
+                    {space}</div>\n",
                 )
             })
             .to_string()
     }
 }
 
+fn to_initial_case(s: &str) -> String {
+    let mut chars = s.chars();
+    let first = chars.next().expect("not empty").to_uppercase();
+    let rest = chars.as_str().to_lowercase();
+    format!("{first}{rest}")
+}
+
 impl Preprocessor for Spec {
     fn name(&self) -> &str {
         "spec"

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/attributes/type_system.md

@@ -163,12 +163,35 @@ match message {
 }
 ```
 
-It's also not allowed to cast non-exhaustive types from foreign crates.
-```rust, ignore
-use othercrate::NonExhaustiveEnum;
+It's also not allowed to use numeric casts (`as`) on enums that contain any non-exhaustive variants.
+
+For example, the following enum can be cast because it doesn't contain any non-exhaustive variants:
+
+```rust
+#[non_exhaustive]
+pub enum Example {
+    First,
+    Second
+}
+```
+
+However, if the enum contains even a single non-exhaustive variant, casting will result in an error. Consider this modified version of the same enum:
+
+```rust
+#[non_exhaustive]
+pub enum EnumWithNonExhaustiveVariants {
+    First,
+    #[non_exhaustive]
+    Second
+}
+```
+
+<!-- ignore: needs multiple crates -->
+```rust,ignore
+use othercrate::EnumWithNonExhaustiveVariants;
 
-// Cannot cast a non-exhaustive enum outside of its defining crate.
-let _ = NonExhaustiveEnum::default() as u8;
+// Error: cannot cast an enum with a non-exhaustive variant when it's defined in another crate
+let _ = EnumWithNonExhaustiveVariants::First as u8;
 ```
 
 Non-exhaustive types are always considered inhabited in downstream crates.

src/behavior-considered-undefined.md

@@ -12,19 +12,10 @@ behaviors. `unsafe` code that satisfies this property for any safe client is
 called *sound*; if `unsafe` code can be misused by safe code to exhibit
 undefined behavior, it is *unsound*.
 
-<div class="warning">
-
-***Warning:*** The following list is not exhaustive; it may grow or shrink.
-There is no formal model of Rust's semantics for what is and is not allowed in
-unsafe code, so there may be more behavior considered unsafe. We also reserve
-the right to make some of the behavior in that list defined in the future. In
-other words, this list does not say that anything will *definitely* always be
-undefined in all future Rust version (but we might make such commitments for
-some list items in the future).
-
-Please read the [Rustonomicon] before writing unsafe code.
-
-</div>
+> [!WARNING]
+> The following list is not exhaustive; it may grow or shrink. There is no formal model of Rust's semantics for what is and is not allowed in unsafe code, so there may be more behavior considered unsafe. We also reserve the right to make some of the behavior in that list defined in the future. In other words, this list does not say that anything will *definitely* always be undefined in all future Rust version (but we might make such commitments for some list items in the future).
+>
+> Please read the [Rustonomicon] before writing unsafe code.
 
 * Data races.
 * Accessing (loading from or storing to) a place that is [dangling] or [based on
@@ -87,7 +78,7 @@ The span of bytes a pointer or reference "points to" is determined by the pointe
 A place is said to be "based on a misaligned pointer" if the last `*` projection
 during place computation was performed on a pointer that was not aligned for its
 type. (If there is no `*` projection in the place expression, then this is
-accessing the field of a local and rustc will guarantee proper alignment. If
+accessing the field of a local or `static` and rustc will guarantee proper alignment. If
 there are multiple `*` projection, then each of them incurs a load of the
 pointer-to-be-dereferenced itself from memory, and each of these loads is
 subject to the alignment constraint. Note that some `*` projections can be

src/comments.md

@@ -1,5 +1,7 @@
 # Comments
 
+r[comments.syntax]
+
 > **<sup>Lexer</sup>**\
 > LINE_COMMENT :\
 > &nbsp;&nbsp; &nbsp;&nbsp; `//` (~\[`/` `!` `\n`] | `//`) ~`\n`<sup>\*</sup>\
@@ -34,27 +36,48 @@
 
 ## Non-doc comments
 
+r[comments.normal]
+
 Comments follow the general C++ style of line (`//`) and
 block (`/* ... */`) comment forms. Nested block comments are supported.
 
+r[comments.normal.tokenization]
 Non-doc comments are interpreted as a form of whitespace.
 
 ## Doc comments
 
+r[comments.doc]
+
+r[comments.doc.syntax]
 Line doc comments beginning with exactly _three_ slashes (`///`), and block
 doc comments (`/** ... */`), both outer doc comments, are interpreted as a
-special syntax for [`doc` attributes]. That is, they are equivalent to writing
+special syntax for [`doc` attributes].
+
+r[comments.doc.attributes]
+That is, they are equivalent to writing
 `#[doc="..."]` around the body of the comment, i.e., `/// Foo` turns into
-`#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`.
+`#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`. They must therefore
+appear before something that accepts an outer attribute.
 
+r[comments.doc.inner-syntax]
 Line comments beginning with `//!` and block comments `/*! ... */` are
 doc comments that apply to the parent of the comment, rather than the item
-that follows.  That is, they are equivalent to writing `#![doc="..."]` around
+that follows.
+
+r[comments.doc.inner-attributes]
+That is, they are equivalent to writing `#![doc="..."]` around
 the body of the comment. `//!` comments are usually used to document
 modules that occupy a source file.
 
+r[comments.doc.bare-crs]
 The character `U+000D` (CR) is not allowed in doc comments.
 
+> **Note**: It is conventional for doc comments to contain Markdown, as expected by
+> `rustdoc`. However, the comment syntax does not respect any internal Markdown.
+> ``/** `glob = "*/*.rs";` */`` terminates the comment at the first `*/`, and the
+> remaining code would cause a syntax error. This slightly limits the content of
+> block doc comments compared to line doc comments.
+
 > **Note**:  The sequence `U+000D` (CR) immediately followed by `U+000A` (LF) would have been previously transformed into a single `U+000A` (LF).
 
 ## Examples

src/conditional-compilation.md

@@ -55,11 +55,8 @@ configuration option from within the source code of the crate being compiled.
 > by [Cargo][cargo-feature] for specifying compile-time options and optional
 > dependencies.
 
-<div class="warning">
-
-Warning: Arbitrarily-set configuration options can clash with compiler-set configuration options. For example, it is possible to do `rustc --cfg "unix" program.rs` while compiling to a Windows target, and have both `unix` and `windows` configuration options set at the same time. Doing this would be unwise.
-
-</div>
+> [!WARNING]
+> Arbitrarily-set configuration options can clash with compiler-set configuration options. For example, it is possible to do `rustc --cfg "unix" program.rs` while compiling to a Windows target, and have both `unix` and `windows` configuration options set at the same time. Doing this would be unwise.
 
 ### `target_arch`
 

src/const_eval.md

@@ -38,8 +38,11 @@ to be run.
 * [Closure expressions] which don't capture variables from the environment.
 * Built-in [negation], [arithmetic], [logical], [comparison] or [lazy boolean]
   operators used on integer and floating point types, `bool`, and `char`.
-* Shared [borrow]s, except if applied to a type with [interior mutability].
-* The [dereference operator] except for raw pointers.
+* All forms of [borrow]s, including raw borrows, with one limitation:
+  mutable borrows and shared borrows to values with interior mutability
+  are only allowed to refer to *transient* places. A place is *transient*
+  if its lifetime is strictly contained inside the current [const context].
+* The [dereference operator].
 * [Grouped] expressions.
 * [Cast] expressions, except
   * pointer to address casts and
@@ -49,6 +52,7 @@ to be run.
 * [if], [`if let`] and [match] expressions.
 
 ## Const context
+[const context]: #const-context
 
 A _const context_ is one of the following:
 
@@ -61,40 +65,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

@@ -80,20 +80,18 @@ r[expr.method.ambiguious-search]
 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.
 >
 > This special case may be removed in the future.
 
-<div class="warning">
+> [!WARNING]
+> For [trait objects], if there is an inherent method of the same name as a trait method, it will give a compiler error when trying to call the method in a method call expression.
+> Instead, you can call the method using [disambiguating function call syntax], in which case it calls the trait method, not the inherent method.
+> There is no way to call the inherent method.
+> Just don't define inherent methods on trait objects with the same name as a trait method and you'll be fine.
 
-***Warning:*** For [trait objects], if there is an inherent method of the same name as a trait method, it will give a compiler error when trying to call the method in a method call expression.
-Instead, you can call the method using [disambiguating function call syntax], in which case it calls the trait method, not the inherent method.
-There is no way to call the inherent method.
-Just don't define inherent methods on trait objects with the same name as a trait method and you'll be fine.
-
-</div>
 
 [_CallParams_]: call-expr.md
 [_Expression_]: ../expressions.md

src/expressions/operator-expr.md

@@ -577,14 +577,10 @@ r[expr.as.int-as-pointer]
 
 Casting from an integer to a raw pointer interprets the integer as a memory address and produces a pointer referencing that memory.
 
-<div class="warning">
-
-Warning:
-This interacts with the Rust memory model, which is still under development.
-A pointer obtained from this cast may suffer additional restrictions even if it is bitwise equal to a valid pointer.
-Dereferencing such a pointer may be [undefined behavior] if aliasing rules are not followed.
-
-</div>
+> [!WARNING]
+> This interacts with the Rust memory model, which is still under development.
+> A pointer obtained from this cast may suffer additional restrictions even if it is bitwise equal to a valid pointer.
+> Dereferencing such a pointer may be [undefined behavior] if aliasing rules are not followed.
 
 A trivial example of sound address arithmetic:
 
@@ -810,14 +806,11 @@ fn example() {
 r[expr.compound-assign.result]
 Like assignment expressions, compound assignment expressions always produce [the unit value][unit].
 
-<div class="warning">
-
-Warning: The evaluation order of operands swaps depending on the types of the operands:
-with primitive types the right-hand side will get evaluated first, while with non-primitive types the left-hand side will get evaluated first.
-Try not to write code that depends on the evaluation order of operands in compound assignment expressions.
-See [this test] for an example of using this dependency.
-
-</div>
+> [!WARNING]
+> The evaluation order of operands swaps depending on the types of the operands:
+> with primitive types the right-hand side will get evaluated first, while with non-primitive types the left-hand side will get evaluated first.
+> Try not to write code that depends on the evaluation order of operands in compound assignment expressions.
+> See [this test] for an example of using this dependency.
 
 [copies or moves]: ../expressions.md#moved-and-copied-types
 [dropping]: ../destructors.md