Rollup merge of #115560 - ShE3py:format-results, r=dtolnay

Update doc for `alloc::format!` and `core::concat!`

Closes #115551.

Used comments instead of `assert!`s as [`std::fmt`](https://doc.rust-lang.org/std/fmt/index.html#usage) uses comments.

Should all the str-related macros (`format!`, `format_args!`, `concat!`, `stringify!`, `println!`, `writeln!`, etc.) references each others? For instance, [`concat!`](https://doc.rust-lang.org/core/macro.concat.html) mentions that integers are stringified, but don't link to `stringify!`.

`@rustbot` label +A-docs +A-fmt

1 files changed, 9 insertions, 5 deletions

diff --git a/library/alloc/src/macros.rs b/library/alloc/src/macros.rs
index 3f19561e1ac..0f767df6063 100644
--- a/library/alloc/src/macros.rs
+++ b/library/alloc/src/macros.rs
@@ -88,15 +88,19 @@ macro_rules! vec {
 ///
 /// A common use for `format!` is concatenation and interpolation of strings.
 /// The same convention is used with [`print!`] and [`write!`] macros,
-/// depending on the intended destination of the string.
+/// depending on the intended destination of the string; all these macros internally use [`format_args!`].
 ///
 /// To convert a single value to a string, use the [`to_string`] method. This
 /// will use the [`Display`] formatting trait.
 ///
+/// To concatenate literals into a `&'static str`, use the [`concat!`] macro.
+///
 /// [`print!`]: ../std/macro.print.html
 /// [`write!`]: core::write
+/// [`format_args!`]: core::format_args
 /// [`to_string`]: crate::string::ToString
 /// [`Display`]: core::fmt::Display
+/// [`concat!`]: core::concat
 ///
 /// # Panics
 ///
@@ -107,11 +111,11 @@ macro_rules! vec {
 /// # Examples
 ///
 /// ```
-/// format!("test");
-/// format!("hello {}", "world!");
-/// format!("x = {}, y = {y}", 10, y = 30);
+/// format!("test");                             // => "test"
+/// format!("hello {}", "world!");               // => "hello world!"
+/// format!("x = {}, y = {val}", 10, val = 30);  // => "x = 10, y = 30"
 /// let (x, y) = (1, 2);
-/// format!("{x} + {y} = 3");
+/// format!("{x} + {y} = 3");                    // => "1 + 2 = 3"
 /// ```
 #[macro_export]
 #[stable(feature = "rust1", since = "1.0.0")]