From c513b0d203d246d1238856f2c987b4feb13cd716 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 28 Apr 2022 12:11:04 +0100 Subject: [PATCH 1/7] panic macro: Document edition differences Having a section for this inspired by the docs for array::IntoIterator --- library/core/src/macros/panic.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md index 98fb7e9e41d7a..6776545585df3 100644 --- a/library/core/src/macros/panic.md +++ b/library/core/src/macros/panic.md @@ -64,6 +64,25 @@ For more detailed information about error handling check out the [book] or the If the main thread panics it will terminate all your threads and end your program with code `101`. +# Editions + +In Rust Editions prior to 2021, `std::panic!(x)` with a single +argument is equivalent to +[`std::panic::panic_any(x)`](../std/panic/fn.panic_any.html). +This is true even if the argument is a string literal. + +For example, in Rust 2015 `panic!("problem: {reason}")` panics with a +payload of literally `"problem: {reason}"` (a `&'static str`), which +is probably not what was intended. In current Rust this usage +captures and formats a variable `reason` from the surrounding scope. + +In Rust editions prior to 2021, `core::panic!(x)` requires that +`x` be `&str`, but does not require it to be a literal. In Rust 2021, +these cases must be written `panic!("{}", x)`. + +In Rust 2021 and later, `panic!` always requires a format string and +the applicable format arguments, and is the same in `core` and `std`. + # Examples ```should_panic From 562c89c78bee44985ead5b3ef191d9b7655782b7 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 28 Apr 2022 13:44:45 +0100 Subject: [PATCH 2/7] Document fmt implicit args required Rust version. For most things in the stdlib, there's the rustdoc-generated version annotations. I don't think we can do this here, so just write prose. I have tried to be as terse as possible while still noting the relevant gotchas. --- library/alloc/src/fmt.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/library/alloc/src/fmt.rs b/library/alloc/src/fmt.rs index 501a6353b2c97..d794b4f672d88 100644 --- a/library/alloc/src/fmt.rs +++ b/library/alloc/src/fmt.rs @@ -84,6 +84,7 @@ //! //! If a named parameter does not appear in the argument list, `format!` will //! reference a variable with that name in the current scope. +//! (Rust 1.58 and later; in [`panic!`], requires Rust 2021.) //! //! ``` //! let argument = 2 + 2; From 1720711a597771650b6c4448c16be8921a5d611b Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 28 Apr 2022 14:29:07 +0100 Subject: [PATCH 3/7] panic macro: Link directly to format syntax, not to format! --- library/core/src/macros/panic.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md index 6776545585df3..459bc2553f266 100644 --- a/library/core/src/macros/panic.md +++ b/library/core/src/macros/panic.md @@ -9,7 +9,7 @@ tests. `panic!` is closely tied with the `unwrap` method of both `panic!` when they are set to [`None`] or [`Err`] variants. When using `panic!()` you can specify a string payload, that is built using -the [`format!`] syntax. That payload is used when injecting the panic into +the [`format!` syntax]. That payload is used when injecting the panic into the calling Rust thread, causing the thread to panic entirely. The behavior of the default `std` hook, i.e. the code that runs directly @@ -55,7 +55,7 @@ For more detailed information about error handling check out the [book] or the [`panic_any`]: ../std/panic/fn.panic_any.html [`Box`]: ../std/boxed/struct.Box.html [`Any`]: crate::any::Any -[`format!`]: ../std/macro.format.html +[`format!` syntax]: ../std/fmt/index.html [book]: ../book/ch09-00-error-handling.html [`std::result`]: ../std/result/index.html From 243f177efb7105e33f5021eb45ebb487431b9efd Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 28 Apr 2022 14:33:30 +0100 Subject: [PATCH 4/7] print macros: add xrefs to format syntax documentation --- library/std/src/macros.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/library/std/src/macros.rs b/library/std/src/macros.rs index c597fb5df45d2..2479f101809ae 100644 --- a/library/std/src/macros.rs +++ b/library/std/src/macros.rs @@ -30,6 +30,9 @@ macro_rules! panic { /// Use `print!` only for the primary output of your program. Use /// [`eprint!`] instead to print error and progress messages. /// +/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) +/// for details of the macro argument syntax. +/// /// [flush]: crate::io::Write::flush /// /// # Panics @@ -76,6 +79,9 @@ macro_rules! print { /// Use `println!` only for the primary output of your program. Use /// [`eprintln!`] instead to print error and progress messages. /// +/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) +/// for details of the macro argument syntax. +/// /// [`std::fmt`]: crate::fmt /// /// # Panics @@ -116,6 +122,9 @@ macro_rules! println { /// [`io::stderr`]: crate::io::stderr /// [`io::stdout`]: crate::io::stdout /// +/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) +/// for details of the macro argument syntax. +/// /// # Panics /// /// Panics if writing to `io::stderr` fails. @@ -144,6 +153,9 @@ macro_rules! eprint { /// Use `eprintln!` only for error and progress messages. Use `println!` /// instead for the primary output of your program. /// +/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) +/// for details of the macro argument syntax. +/// /// [`io::stderr`]: crate::io::stderr /// [`io::stdout`]: crate::io::stdout /// From 58b0ab529372c5916a5ca62b545355aa5ae14943 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 28 Apr 2022 14:27:57 +0100 Subject: [PATCH 5/7] format macro: Make xref to std::fmt much more prominent That xref contains the actual documentation for what format! does. It should be very prominent - particularly, more so than the other links. --- library/alloc/src/macros.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/library/alloc/src/macros.rs b/library/alloc/src/macros.rs index 22c19243e7f53..6f1b6b800e351 100644 --- a/library/alloc/src/macros.rs +++ b/library/alloc/src/macros.rs @@ -73,10 +73,12 @@ macro_rules! vec { /// /// The first argument `format!` receives is a format string. This must be a string /// literal. The power of the formatting string is in the `{}`s contained. -/// /// Additional parameters passed to `format!` replace the `{}`s within the /// formatting string in the order given unless named or positional parameters -/// are used; see [`std::fmt`] for more information. +/// are used. +/// +/// See [the formatting syntax documentation in `std::fmt`](../std/fmt/index.html) +/// for details. /// /// A common use for `format!` is concatenation and interpolation of strings. /// The same convention is used with [`print!`] and [`write!`] macros, @@ -85,7 +87,6 @@ macro_rules! vec { /// To convert a single value to a string, use the [`to_string`] method. This /// will use the [`Display`] formatting trait. /// -/// [`std::fmt`]: ../std/fmt/index.html /// [`print!`]: ../std/macro.print.html /// [`write!`]: core::write /// [`to_string`]: crate::string::ToString From bd0f0598097bf32b2876b66f18e1107afa178072 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 28 Apr 2022 14:39:52 +0100 Subject: [PATCH 6/7] format_args: Make xref to format argument syntax much more prominent --- library/core/src/macros/mod.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index 83f33ca007af1..503bd10de4c98 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -849,7 +849,8 @@ pub(crate) mod builtin { /// assert_eq!(display, debug); /// ``` /// - /// For more information, see the documentation in [`std::fmt`]. + /// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) + /// for details of the macro argument syntax, and further information. /// /// [`Display`]: crate::fmt::Display /// [`Debug`]: crate::fmt::Debug From 8be3d46b1a0f1f582b8c57b17f6c56deb087bf27 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 28 Apr 2022 17:45:13 +0100 Subject: [PATCH 7/7] Fix trailing whitespace --- library/core/src/macros/panic.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md index 459bc2553f266..46b9bc7151d26 100644 --- a/library/core/src/macros/panic.md +++ b/library/core/src/macros/panic.md @@ -73,7 +73,7 @@ This is true even if the argument is a string literal. For example, in Rust 2015 `panic!("problem: {reason}")` panics with a payload of literally `"problem: {reason}"` (a `&'static str`), which -is probably not what was intended. In current Rust this usage +is probably not what was intended. In current Rust this usage captures and formats a variable `reason` from the surrounding scope. In Rust editions prior to 2021, `core::panic!(x)` requires that