Rollup merge of #26678 - bluss:doc-fmt, r=steveklabnik

fmt: Update docs and mention :#? pretty-printing

Expose `:#?` well in the docs for fmt and Debug itself. Also update some out of date information and fix formatting in `std::fmt` docs.

2 files changed, 27 insertions, 23 deletions

diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs
index 72d0ca85357..7df259e9b36 100644
--- a/src/libcollections/fmt.rs
+++ b/src/libcollections/fmt.rs
@@ -128,15 +128,15 @@
 //! This allows multiple actual types to be formatted via `{:x}` (like `i8` as
 //! well as `isize`).  The current mapping of types to traits is:
 //!
-//! * *nothing* ⇒ `Display`
-//! * `?` ⇒ `Debug`
-//! * `o` ⇒ `Octal`
-//! * `x` ⇒ `LowerHex`
-//! * `X` ⇒ `UpperHex`
-//! * `p` ⇒ `Pointer`
-//! * `b` ⇒ `Binary`
-//! * `e` ⇒ `LowerExp`
-//! * `E` ⇒ `UpperExp`
+//! * *nothing* ⇒ [`Display`](trait.Display.html)
+//! * `?` ⇒ [`Debug`](trait.Debug.html)
+//! * `o` ⇒ [`Octal`](trait.Octal.html)
+//! * `x` ⇒ [`LowerHex`](trait.LowerHex.html)
+//! * `X` ⇒ [`UpperHex`](trait.UpperHex.html)
+//! * `p` ⇒ [`Pointer`](trait.Pointer.html)
+//! * `b` ⇒ [`Binary`](trait.Binary.html)
+//! * `e` ⇒ [`LowerExp`](trait.LowerExp.html)
+//! * `E` ⇒ [`UpperExp`](trait.UpperExp.html)
 //!
 //! What this means is that any type of argument which implements the
 //! `fmt::Binary` trait can then be formatted with `{:b}`. Implementations
@@ -367,11 +367,11 @@
 //!         should always be printed.
 //! * '-' - Currently not used
 //! * '#' - This flag is indicates that the "alternate" form of printing should
-//!         be used.  For array slices, the alternate form omits the brackets.
-//!         For the integer formatting traits, the alternate forms are:
+//!         be used. The alternate forms are:
+//!     * `#?` - pretty-print the `Debug` formatting
 //!     * `#x` - precedes the argument with a "0x"
 //!     * `#X` - precedes the argument with a "0x"
-//!     * `#t` - precedes the argument with a "0b"
+//!     * `#b` - precedes the argument with a "0b"
 //!     * `#o` - precedes the argument with a "0o"
 //! * '0' - This is used to indicate for integer formats that the padding should
 //!         both be done with a `0` character as well as be sign-aware. A format
@@ -408,19 +408,20 @@
 //!
 //! There are three possible ways to specify the desired `precision`:
 //!
-//! There are three possible ways to specify the desired `precision`:
-//! 1. An integer `.N`,
-//! 2. an integer followed by dollar sign `.N$`, or
-//! 3. an asterisk `.*`.
+//! 1. An integer `.N`:
+//!
+//!    the integer `N` itself is the precision.
+//!
+//! 2. An integer followed by dollar sign `.N$`:
 //!
-//! The first specification, `.N`, means the integer `N` itself is the precision.
+//!    use format *argument* `N` (which must be a `usize`) as the precision.
 //!
-//! The second, `.N$`, means use format *argument* `N` (which must be a `usize`) as the precision.
+//! 3. An asterisk `.*`:
 //!
-//! Finally,  `.*` means that this `{...}` is associated with *two* format inputs rather than one:
-//! the first input holds the `usize` precision, and the second holds the value to print.  Note
-//! that in this case, if one uses the format string `{<arg>:<spec>.*}`, then the `<arg>` part
-//! refers to the *value* to print, and the `precision` must come in the input preceding `<arg>`.
+//!    `.*` means that this `{...}` is associated with *two* format inputs rather than one: the
+//!    first input holds the `usize` precision, and the second holds the value to print.  Note that
+//!    in this case, if one uses the format string `{<arg>:<spec>.*}`, then the `<arg>` part refers
+//!    to the *value* to print, and the `precision` must come in the input preceding `<arg>`.
 //!
 //! For example, these:
 //!
diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs
index cbbb186af76..35dea6d15f0 100644
--- a/src/libcore/fmt/mod.rs
+++ b/src/libcore/fmt/mod.rs
@@ -267,7 +267,7 @@ impl<'a> Display for Arguments<'a> {
     }
 }
 
-/// Format trait for the `:?` format. Useful for debugging, all types
+/// Format trait for the `?` character. Useful for debugging, all types
 /// should implement this.
 ///
 /// Generally speaking, you should just `derive` a `Debug` implementation.
@@ -312,6 +312,9 @@ impl<'a> Display for Arguments<'a> {
 /// There are a number of `debug_*` methods on `Formatter` to help you with manual
 /// implementations, such as [`debug_struct`][debug_struct].
 ///
+/// `Debug` implementations using either `derive` or the debug builder API
+/// on `Formatter` support pretty printing using the alternate flag: `{:#?}`.
+///
 /// [debug_struct]: ../std/fmt/struct.Formatter.html#method.debug_struct
 #[stable(feature = "rust1", since = "1.0.0")]
 #[rustc_on_unimplemented = "`{Self}` cannot be formatted using `:?`; if it is \