From 815987b4ce9c1649133263b388903322dd77ea6c Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Thu, 28 Apr 2016 17:49:10 +0200
Subject: [PATCH] Clarify std::fmt width docs w.r.t. dollar syntax and give
 example.

---
 src/libcollections/fmt.rs | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs
index e30e0b213afa..710a30ff2364 100644
--- a/src/libcollections/fmt.rs
+++ b/src/libcollections/fmt.rs
@@ -395,8 +395,19 @@
 //! `0`.
 //!
 //! The value for the width can also be provided as a `usize` in the list of
-//! parameters by using the `2$` syntax indicating that the second argument is a
-//! `usize` specifying the width.
+//! parameters by using the dollar syntax indicating that the second argument is
+//! a `usize` specifying the width, for example:
+//!
+//! ```
+//! // All of these print "Hello x    !"
+//! println!("Hello {:5}!", "x");
+//! println!("Hello {:1$}!", "x", 5);
+//! println!("Hello {1:0$}!", 5, "x");
+//! ```
+//!
+//! 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 all arguments by
+//! their position explicitly.
 //!
 //! ## Precision
 //!