From 96ea9845bd6b7058d2e3deb74a83204bc5abb1b7 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Wed, 30 Oct 2024 04:31:26 +0000 Subject: [PATCH] Prepare PR #329 to be merged We made an editorial pass over this. --- src/SUMMARY.md | 2 +- .../rustdoc-doctests-nested-include-str.md | 64 ------------------- src/rust-2024/rustdoc-nested-includes.md | 63 ++++++++++++++++++ 3 files changed, 64 insertions(+), 65 deletions(-) delete mode 100644 src/rust-2024/rustdoc-doctests-nested-include-str.md create mode 100644 src/rust-2024/rustdoc-nested-includes.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c5b8e4a6..8e69ec06 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -56,5 +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) - - [Rustdoc doctest nested `include_str!` change](rust-2024/rustdoc-doctests-nested-include-str.md) diff --git a/src/rust-2024/rustdoc-doctests-nested-include-str.md b/src/rust-2024/rustdoc-doctests-nested-include-str.md deleted file mode 100644 index 0ed284ee..00000000 --- a/src/rust-2024/rustdoc-doctests-nested-include-str.md +++ /dev/null @@ -1,64 +0,0 @@ -# Rustdoc doctest nested `include_str!` change - -🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". -More information may be found at . - -## Summary - -When a doctest is included with `include_str!`, if that doctest itself -also uses `include!` / `include_str!` / `include_bytes!`, the path is -resolved relative to the Markdown file, rather than 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 the doctests. As a result, if the Markdown file is in a different -directory than the source, any `include!`ed paths need to be relative -to the Rust file. - -For example, consider a library crate with these files: - -* Cargo.toml -* README.md -* src/ - * lib.rs -* examples/ - * data.bin - -Let `lib.rs` contain 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` iself. - -## Migration - -After migrating, you'll see the following error: - -```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"); - | ~~~~~~~~~~~~~~~~~~~ -``` diff --git a/src/rust-2024/rustdoc-nested-includes.md b/src/rust-2024/rustdoc-nested-includes.md new file mode 100644 index 00000000..301e3745 --- /dev/null +++ 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 . + +## 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.