From 9a5aa90516602b288de34dd65161d90f2db202a6 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Mon, 12 Jan 2026 09:34:11 -0800
Subject: [PATCH] Add some clarifications and fixes for fmt syntax

This tries to clarify a few things regarding fmt syntax:

- The comment on `Parser::word` seems to be wrong, as that
  underscore-prefixed words are just fine. This was changed in
  https://github.com/rust-lang/rust/pull/66847.
- I struggled to follow the description of the width argument. It
  referred to a "second argument", but I don't know what second argument
  it is referring to (which is the first?). Either way, I rewrote the
  paragraph to try to be a little more explicit, and to use shorter
  sentences.
- The description of the precision argument wasn't really clear about
  the distinction of an Nth argument and a named argument. I added
  a sentence to try to emphasize the difference.
- `IDENTIFIER_OR_KEYWORD` was changed recently in
  https://github.com/rust-lang/reference/pull/2049 to include bare `_`.
  But fmt named arguments are not allowed to be a bare `_`.
---
 compiler/rustc_parse_format/src/lib.rs |  2 +-
 library/alloc/src/fmt.rs               | 15 ++++++++++-----
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/compiler/rustc_parse_format/src/lib.rs b/compiler/rustc_parse_format/src/lib.rs
index 86326fc6536cd..a687a45480dcd 100644
--- a/compiler/rustc_parse_format/src/lib.rs
+++ b/compiler/rustc_parse_format/src/lib.rs
@@ -753,7 +753,7 @@ impl<'input> Parser<'input> {
     }
 
     /// Parses a word starting at the current position. A word is the same as a
-    /// Rust identifier, except that it can't start with `_` character.
+    /// Rust identifier or keyword, except that it can't be a bare `_` character.
     fn word(&mut self) -> &'input str {
         let index = self.input_vec_index;
         match self.peek() {
diff --git a/library/alloc/src/fmt.rs b/library/alloc/src/fmt.rs
index 3d7c580be8c95..e3ff2ba51aba0 100644
--- a/library/alloc/src/fmt.rs
+++ b/library/alloc/src/fmt.rs
@@ -136,9 +136,10 @@
 //! padding specified by fill/alignment will be used to take up the required
 //! space (see below).
 //!
-//! The value for the width can also be provided as a [`usize`] in the list of
-//! parameters by adding a postfix `$`, indicating that the second argument is
-//! a [`usize`] specifying the width.
+//! The width can also be provided dynamically by referencing another argument
+//! with a `$` suffix. Use `{:N$}` to reference the Nth positional argument
+//! (where N is an integer), or `{:name$}` to reference a named argument. The
+//! referenced argument must be of type [`usize`].
 //!
 //! Referring to an argument with the dollar syntax does not affect the "next
 //! argument" counter, so it's usually a good idea to refer to arguments by
@@ -236,7 +237,8 @@
 //!
 //! 2. An integer or name followed by dollar sign `.N$`:
 //!
-//!    use format *argument* `N` (which must be a `usize`) as the precision.
+//!    use the value of format *argument* `N` (which must be a `usize`) as the precision.
+//!    An integer refers to a positional argument, and a name refers to a named argument.
 //!
 //! 3. An asterisk `.*`:
 //!
@@ -363,7 +365,10 @@
 //! - `ws` is any character for which [`char::is_whitespace`] returns `true`, has no semantic
 //!   meaning and is completely optional,
 //! - `integer` is a decimal integer that may contain leading zeroes and must fit into an `usize` and
-//! - `identifier` is an `IDENTIFIER_OR_KEYWORD` (not an `IDENTIFIER`) as defined by the [Rust language reference](https://doc.rust-lang.org/reference/identifiers.html).
+//! - `identifier` is an `IDENTIFIER_OR_KEYWORD` (not an `IDENTIFIER`) as
+//!   defined by the [Rust language
+//!   reference](https://doc.rust-lang.org/reference/identifiers.html), except
+//!   for a bare `_`.
 //!
 //! # Formatting traits
 //!