Document #[diagnostic::on_move] in the unstable book.

[mejrs]

Also adds the attribute on std::fs::File to stay consistent with the prose in the unstable book entry.

cc @estebank @rperier

Rendered:

[rustbot]

r? @chenyukang

rustbot has assigned @chenyukang.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: compiler
• compiler expanded to 72 candidates
• Random selection from 17 candidates

[rust-log-analyzer]

The job aarch64-gnu-llvm-21-2 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

Executing "/scripts/stage_2_test_set2.sh"
+ /scripts/stage_2_test_set2.sh
PR_CI_JOB set; skipping tidy
+ '[' 1 == 1 ']'
+ echo 'PR_CI_JOB set; skipping tidy'
+ SKIP_TIDY='--skip tidy'
+ ../x.py --stage 2 test --skip tidy --skip tests --skip coverage-map --skip coverage-run --skip library --skip tidyselftest
##[group]Building bootstrap
    Finished `dev` profile [unoptimized] target(s) in 0.04s
##[endgroup]
downloading https://static.rust-lang.org/dist/2026-04-14/rustfmt-nightly-aarch64-unknown-linux-gnu.tar.xz
---
   |
78 | error[E0382]: `Token` cannot be used multiple times
   |               ^
   |
help: Unicode character '`' (Grave Accent) looks like ''' (Single Quote), but it is not
   |
78 - error[E0382]: `Token` cannot be used multiple times
78 + error[E0382]: 'Token` cannot be used multiple times
   |

error: unknown start of token: `
##[error]  --> /checkout/src/doc/unstable-book/src/language-features/diagnostic-on-move.md:78:21
   |
78 | error[E0382]: `Token` cannot be used multiple times
   |                     ^
   |
help: Unicode character '`' (Grave Accent) looks like ''' (Single Quote), but it is not
   |
78 - error[E0382]: `Token` cannot be used multiple times
78 + error[E0382]: `Token' cannot be used multiple times
   |

error: unknown start of token: `
##[error]  --> /checkout/src/doc/unstable-book/src/language-features/diagnostic-on-move.md:88:33
   |
88 |    = note: you can create a new `Token` with `Token::conjure()`
   |                                 ^
   |
help: Unicode character '`' (Grave Accent) looks like ''' (Single Quote), but it is not
   |
88 -    = note: you can create a new `Token` with `Token::conjure()`
88 +    = note: you can create a new 'Token` with `Token::conjure()`
   |

error: unknown start of token: `
##[error]  --> /checkout/src/doc/unstable-book/src/language-features/diagnostic-on-move.md:88:39
   |
88 |    = note: you can create a new `Token` with `Token::conjure()`
   |                                       ^
   |
help: Unicode character '`' (Grave Accent) looks like ''' (Single Quote), but it is not
   |
88 -    = note: you can create a new `Token` with `Token::conjure()`
88 +    = note: you can create a new `Token' with `Token::conjure()`
   |

error: unknown start of token: `
##[error]  --> /checkout/src/doc/unstable-book/src/language-features/diagnostic-on-move.md:88:46
   |
88 |    = note: you can create a new `Token` with `Token::conjure()`
   |                                              ^
   |
help: Unicode character '`' (Grave Accent) looks like ''' (Single Quote), but it is not
   |
88 -    = note: you can create a new `Token` with `Token::conjure()`
88 +    = note: you can create a new `Token` with 'Token::conjure()`
   |

error: unknown start of token: `
##[error]  --> /checkout/src/doc/unstable-book/src/language-features/diagnostic-on-move.md:88:63
   |
88 |    = note: you can create a new `Token` with `Token::conjure()`
   |                                                               ^
   |
help: Unicode character '`' (Grave Accent) looks like ''' (Single Quote), but it is not
   |
88 -    = note: you can create a new `Token` with `Token::conjure()`
88 +    = note: you can create a new `Token` with `Token::conjure()'
   |

error: expected one of `!` or `::`, found `[`
##[error]  --> /checkout/src/doc/unstable-book/src/language-features/diagnostic-on-move.md:78:6
   |
78 | error[E0382]: `Token` cannot be used multiple times
   |      ^ expected one of `!` or `::`

---
   |          -----  ^^^^^ value used here after move
   |          |
   |          value moved here
   |
   = note: you can create a new `Token` with `Token::conjure()`
note: if `Token<'_>` implemented `Clone`, you could clone the value
  --> /checkout/src/doc/unstable-book/src/language-features/diagnostic-on-move.md:61:1
   |
61 | pub struct Token<'brand> {
   | ^^^^^^^^^^^^^^^^^^^^^^^^ consider implementing `Clone` for this type
...
74 | let _ = (token, token);
   |          ----- you could clone this value

---

test result: FAILED. 2 passed; 2 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.12s

Bootstrap failed while executing `--stage 2 test --skip tidy --skip tests --skip coverage-map --skip coverage-run --skip library --skip tidyselftest`
Command `/checkout/obj/build/bootstrap/debug/rustdoc -Wrustdoc::invalid_codeblock_attributes -Dwarnings -Znormalize-docs -Z unstable-options --test /checkout/src/doc/unstable-book/src/language-features/diagnostic-on-move.md --test-args ` failed with exit code 101
Created at: src/bootstrap/src/core/builder/mod.rs:1463:23
Executed at: src/bootstrap/src/core/build_steps/test.rs:2910:13

--- BACKTRACE vvv
   0: std::backtrace_rs::backtrace::libunwind::trace
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/../../backtrace/src/backtrace/libunwind.rs:117:9
   1: std::backtrace_rs::backtrace::trace_unsynchronized::<<std::backtrace::Backtrace>::create::{closure#0}>
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/../../backtrace/src/backtrace/mod.rs:66:14
   2: <std::backtrace::Backtrace>::create
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/backtrace.rs:331:13
   3: <bootstrap::utils::exec::DeferredCommand>::finish_process
             at /checkout/src/bootstrap/src/utils/exec.rs:939:17
   4: <bootstrap::utils::exec::DeferredCommand>::wait_for_output::<&bootstrap::utils::exec::ExecutionContext>
             at /checkout/src/bootstrap/src/utils/exec.rs:831:21
   5: <bootstrap::utils::exec::ExecutionContext>::run
             at /checkout/src/bootstrap/src/utils/exec.rs:741:45
   6: <bootstrap::utils::exec::BootstrapCommand>::run::<&bootstrap::core::builder::Builder>
             at /checkout/src/bootstrap/src/utils/exec.rs:339:27
   7: bootstrap::core::build_steps::test::markdown_test
             at /checkout/src/bootstrap/src/core/build_steps/test.rs:2910:13
   8: <bootstrap::core::build_steps::test::BookTest>::run_local_doc
             at /checkout/src/bootstrap/src/core/build_steps/test.rs:2750:13
---
  12: <bootstrap::core::builder::Builder>::ensure::<bootstrap::core::build_steps::test::UnstableBook>
             at /checkout/src/bootstrap/src/core/builder/mod.rs:1579:36
  13: <bootstrap::core::build_steps::test::UnstableBook as bootstrap::core::builder::Step>::make_run
             at /checkout/src/bootstrap/src/core/build_steps/test.rs:2782:33
  14: <bootstrap::core::builder::StepDescription>::maybe_run
             at /checkout/src/bootstrap/src/core/builder/mod.rs:476:13
  15: bootstrap::core::builder::cli_paths::match_paths_to_steps_and_run
             at /checkout/src/bootstrap/src/core/builder/cli_paths.rs:141:22
  16: <bootstrap::core::builder::Builder>::run_step_descriptions
             at /checkout/src/bootstrap/src/core/builder/mod.rs:1122:9
  17: <bootstrap::core::builder::Builder>::execute_cli
             at /checkout/src/bootstrap/src/core/builder/mod.rs:1101:14
  18: <bootstrap::Build>::build
             at /checkout/src/bootstrap/src/lib.rs:799:25
  19: bootstrap::main
             at /checkout/src/bootstrap/src/bin/main.rs:130:11
  20: <fn() as core::ops::function::FnOnce<()>>::call_once
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/core/src/ops/function.rs:250:5
  21: std::sys::backtrace::__rust_begin_short_backtrace::<fn(), ()>
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/sys/backtrace.rs:166:18
  22: std::rt::lang_start::<()>::{closure#0}
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/rt.rs:206:18
  23: <&dyn core::ops::function::Fn<(), Output = i32> + core::panic::unwind_safe::RefUnwindSafe + core::marker::Sync as core::ops::function::FnOnce<()>>::call_once
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/core/src/ops/function.rs:287:21
  24: std::panicking::catch_unwind::do_call::<&dyn core::ops::function::Fn<(), Output = i32> + core::panic::unwind_safe::RefUnwindSafe + core::marker::Sync, i32>
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/panicking.rs:581:40
  25: std::panicking::catch_unwind::<i32, &dyn core::ops::function::Fn<(), Output = i32> + core::panic::unwind_safe::RefUnwindSafe + core::marker::Sync>
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/panicking.rs:544:19
  26: std::panic::catch_unwind::<&dyn core::ops::function::Fn<(), Output = i32> + core::panic::unwind_safe::RefUnwindSafe + core::marker::Sync, i32>
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/panic.rs:359:14
  27: std::rt::lang_start_internal::{closure#0}
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/rt.rs:175:24
  28: std::panicking::catch_unwind::do_call::<std::rt::lang_start_internal::{closure#0}, isize>
             at /rustc/ef0fb8a2563200e322fa4419f09f65a63742038c/library/std/src/panicking.rs:581:40
---
  35: __libc_start_main
  36: _start


Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:46:06
  local time: Tue Apr 21 22:38:23 UTC 2026
  network time: Tue, 21 Apr 2026 22:38:24 GMT
##[error]Process completed with exit code 1.
##[group]Run echo "disk usage:"

[rperier]

I would put the same kind of details in the diagnostic attribute of std::fs::File than on Rc and Arc (see 92ed4a2) : the idea being explain briefly why the user can use try_clone or clone , because it's cheap or designed for that purpose (or another reason). And then, you can then refer to File::try_clone from the notes. Because currently the compiler already talks about .clone() when the type implements the Clone trait, so just a supplementary note refering to File::try_clone is a bit confusing, imho. Providing more context to the user would be helpful.

+1 for the documentation, good idea ;)