Merge PR #329: Fix doctest include paths

traviscross · traviscross · commit 0386f153586e · 2024-10-30T04:46:03.000Z
diff --git a/book.toml b/book.toml
@@ -80,6 +80,7 @@ search.use-boolean-and = true
 "/rust-2018/platform-and-target-support/msvc-toolchain-support.html" = "../../../rustc/platform-support.html"
 "/rust-2018/platform-and-target-support/musl-support-for-fully-static-binaries.html" = "../../../rustc/platform-support.html"
 "/rust-2018/platform-and-target-support/cdylib-crates-for-c-interoperability.html" = "https://github.com/rust-lang/rfcs/blob/master/text/1510-cdylib.md"
+"/rust-2021/reserving-syntax.html" = "reserved-syntax.html"
 "/rust-next/index.html" = "../rust-2021/index.html"
 "/rust-next/edition-changes.html" = "../rust-2021/index.html"
 "/rust-next/dbg-macro.html" = "../../std/macro.dbg.html"
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -30,7 +30,7 @@
   - [IntoIterator for arrays](rust-2021/IntoIterator-for-arrays.md)
   - [Disjoint capture in closures](rust-2021/disjoint-capture-in-closures.md)
   - [Panic macro consistency](rust-2021/panic-macro-consistency.md)
-  - [Reserving syntax](rust-2021/reserving-syntax.md)
+  - [Reserved syntax](rust-2021/reserved-syntax.md)
   - [Warnings promoted to errors](rust-2021/warnings-promoted-to-error.md)
   - [Or patterns in macro-rules](rust-2021/or-patterns-macro-rules.md)
   - [C-string literals](rust-2021/c-string-literals.md)
@@ -44,6 +44,7 @@
   - [`unsafe_op_in_unsafe_fn` warning](rust-2024/unsafe-op-in-unsafe-fn.md)
   - [RPIT lifetime capture rules](rust-2024/rpit-lifetime-capture.md)
   - [Disallow references to `static mut`](rust-2024/static-mut-references.md)
+  - [Cargo: Rust-version aware resolver](rust-2024/cargo-resolver.md)
   - [Cargo: Table and key name consistency](rust-2024/cargo-table-key-names.md)
   - [Cargo: Reject unused inherited default-features](rust-2024/cargo-inherited-default-features.md)
   - [Rustfmt: Combine all delimited exprs as last argument](rust-2024/rustfmt-overflow-delimited-expr.md)
@@ -55,3 +56,5 @@
   - [Unsafe `extern` blocks](rust-2024/unsafe-extern.md)
   - [Unsafe attributes](rust-2024/unsafe-attributes.md)
   - [Rustdoc combined tests](rust-2024/rustdoc-doctests.md)
+  - [Rustdoc nested `include!` change](rust-2024/rustdoc-nested-includes.md)
+  - [Reserved syntax](rust-2024/reserved-syntax.md)
diff --git a/src/rust-2021/c-string-literals.md b/src/rust-2021/c-string-literals.md
@@ -69,4 +69,4 @@ Migration is only necessary for macros which may have been assuming a sequence o
 As part of the [syntax reservation] for the 2021 edition, any macro input which may run into this issue should issue a warning from the `rust_2021_prefixes_incompatible_syntax` migration lint.
 See that chapter for more detail.
 
-[syntax reservation]: reserving-syntax.md
+[syntax reservation]: reserved-syntax.md
diff --git a/src/rust-2021/reserved-syntax.md b/src/rust-2021/reserved-syntax.md
@@ -1,4 +1,4 @@
-# Reserving syntax
+# Reserved syntax
 
 ## Summary
 
diff --git a/src/rust-2024/cargo-resolver.md b/src/rust-2024/cargo-resolver.md
@@ -0,0 +1,38 @@
+# Cargo: Rust-version aware resolver
+
+🚧 The 2024 Edition has not yet been released and hence this section is still "under construction".
+
+## Summary
+
+- `edition = "2024"` implies `resolver = "3"` in `Cargo.toml` which enables a Rust-version aware dependency resolver.
+
+## Details
+
+Since Rust 1.84.0, Cargo has opt-in support for compatibility with
+[`package.rust-version`] to be considered when selecting dependency versions
+by setting [`resolver.incompatible-rust-version = "fallback"`] in `.cargo/config.toml`.
+
+Starting in Rust 2024, this will be the default.
+That is, writing `edition = "2024"` in `Cargo.toml` will imply `resolver = "3"`
+which will imply [`resolver.incompatible-rust-version = "fallback"`].
+
+The resolver is a global setting for a [workspace], and the setting is ignored in dependencies.
+The setting is only honored for the top-level package of the workspace.
+If you are using a [virtual workspace], you will still need to explicitly set the [`resolver` field]
+in the `[workspace]` definition if you want to opt-in to the new resolver.
+
+For more details on how Rust-version aware dependency resolution works, see [the Cargo book](../..//cargo/reference/resolver.html#rust-version).
+
+[`package.rust-version`]: ../../cargo/reference/rust-version.html
+[`resolver.incompatible-rust-version = "fallback"`]: ../../cargo/reference/config.html#resolverincompatible-rust-versions
+[workspace]: ../../cargo/reference/workspaces.html
+[virtual workspace]: ../../cargo/reference/workspaces.html#virtual-workspace
+[`resolver` field]: ../../cargo/reference/resolver.html#resolver-versions
+
+## Migration
+
+There are no automated migration tools for updating for the new resolver.
+
+We recommend projects
+[verify against the latest dependencies in CI](../../cargo/guide/continuous-integration.html#verifying-latest-dependencies)
+to catch bugs in dependencies as soon as possible.
diff --git a/src/rust-2024/reserved-syntax.md b/src/rust-2024/reserved-syntax.md
@@ -0,0 +1,66 @@
+# Reserved syntax
+
+🚧 The 2024 Edition has not yet been released and hence this section is still "under construction".
+More information may be found in the tracking issue at <https://github.com/rust-lang/rust/issues/123735>.
+
+## Summary
+
+- Unprefixed guarded strings of the form `#"foo"#` are reserved for future use.
+- Two or more `#` characters are reserved for future use.
+
+## Details
+
+[RFC 3593] reserved syntax in the 2024 Edition for guarded string literals that do not have a prefix to make room for possible future language changes. The 2021 Edition [reserved syntax][2021] for guarded strings with a prefix, such as `ident##"foo"##`. The 2024 Edition extends that to also reserve strings without the `ident` prefix.
+
+There are two reserved syntaxes:
+
+- One or more `#` characters immediately followed by a [string literal].
+- Two or more `#` characters in a row (not separated by whitespace).
+
+This reservation is done across an edition boundary because of interactions with tokenization and macros. For example, consider this macro:
+
+```rust
+macro_rules! demo {
+    ( $a:tt ) => { println!("one token") };
+    ( $a:tt $b:tt $c:tt ) => { println!("three tokens") };
+}
+
+demo!("foo");
+demo!(r#"foo"#);
+demo!(#"foo"#);
+demo!(###)
+```
+
+Prior to the 2024 Edition, this produces:
+
+```text
+one token
+one token
+three tokens
+three tokens
+```
+
+Starting in the 2024 Edition, the `#"foo"#` line and the `###` line now generates a compile error because those forms are now reserved.
+
+[2021]: ../rust-2021/reserved-syntax.md
+[string literal]: ../../reference/tokens.html#string-literals
+[RFC 3593]: https://rust-lang.github.io/rfcs/3593-unprefixed-guarded-strings.html
+
+## Migration
+
+The [`rust_2024_guarded_string_incompatible_syntax`] lint will identify any tokens that match the reserved syntax, and will suggest a modification to insert spaces where necessary to ensure the tokens continue to be parsed separately.
+
+The lint is part of the `rust-2024-compatibility` lint group which is included in the automatic edition migration. In order to migrate your code to be Rust 2024 Edition compatible, run:
+
+```sh
+cargo fix --edition
+```
+
+Alternatively, you can manually enable the lint to find macro calls where you may need to update the tokens:
+
+```rust
+// Add this to the root of your crate to do a manual migration.
+#![warn(rust_2024_guarded_string_incompatible_syntax)]
+```
+
+[`rust_2024_guarded_string_incompatible_syntax`]: ../../rustc/lints/listing/allowed-by-default.html#rust-2024-guarded-string-incompatible-syntax
diff --git a/src/rust-2024/rustdoc-nested-includes.md b/src/rust-2024/rustdoc-nested-includes.md
@@ -0,0 +1,63 @@
+# Rustdoc nested `include!` change
+
+🚧 The 2024 Edition has not yet been released and hence this section is still "under construction".
+More information may be found in the tracking issue at <https://github.com/rust-lang/rust/issues/132230>.
+
+## Summary
+
+When a doctest is included with `include_str!`, if that doctest itself also uses `include!`, `include_str!`, or `include_bytes!`, the path is resolved relative to the Markdown file, rather than to the Rust source file.
+
+## Details
+
+Prior to the 2024 edition, adding documentation with `#[doc=include_str!("path/file.md")]` didn't carry span information into any doctests in that file. As a result, if the Markdown file was in a different directory than the source, any paths included had to be specified relative to the source file.
+
+For example, consider a library crate with these files:
+
+- `Cargo.toml`
+- `README.md`
+- `src/`
+  - `lib.rs`
+- `examples/`
+  - `data.bin`
+
+Let's say that `lib.rs` contains this:
+
+```rust,ignore
+#![doc=include_str!("../README.md")]
+```
+
+And assume this `README.md` file:
+
+````markdown
+```
+let _ = include_bytes!("../examples/data.bin");
+//                      ^^^ notice this
+```
+````
+
+Prior to the 2024 edition, the path in `README.md` needed to be relative to the `lib.rs` file. In 2024 and later, it is now relative to `README.md` itself, so we would update `README.md` to:
+
+````markdown
+```
+let _ = include_bytes!("examples/data.bin");
+```
+````
+
+## Migration
+
+There is no automatic migration to convert the paths in affected doctests. If one of your doctests is affected, you'll see an error like this after migrating to the new edition when building your tests:
+
+```text
+error: couldn't read `../examples/data.bin`: No such file or directory (os error 2)
+ --> src/../README.md:2:24
+  |
+2 | let _ = include_bytes!("../examples/data.bin");
+  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  = note: this error originates in the macro `include_bytes` (in Nightly builds, run with -Z macro-backtrace for more info)
+help: there is a file with the same name in a different directory
+  |
+2 | let _ = include_bytes!("examples/data.bin");
+  |                        ~~~~~~~~~~~~~~~~~~~
+```
+
+To migrate your doctests to Rust 2024, update any affected paths to be relative to the file containing the doctests.

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Reserving syntax`
	`1`	`+# Reserved syntax`
`2`	`2`
`3`	`3`	`## Summary`
`4`	`4`