Rollup merge of rust-lang#23493 - steveklabnik:gh22927, r=alexcrichton

 And do some formatting while I'm here.

src/libcollections/fmt.rs

@@ -16,7 +16,7 @@
 //! This macro is implemented in the compiler to emit calls to this module in
 //! order to format arguments at runtime into strings and streams.
 //!
-//! ## Usage
+//! # Usage
 //!
 //! The `format!` macro is intended to be familiar to those coming from C's
 //! printf/fprintf functions or Python's `str.format` function. In its current
@@ -41,7 +41,7 @@
 //! will then parse the format string and determine if the list of arguments
 //! provided is suitable to pass to this format string.
 //!
-//! ### Positional parameters
+//! ## Positional parameters
 //!
 //! Each formatting argument is allowed to specify which value argument it's
 //! referencing, and if omitted it is assumed to be "the next argument". For
@@ -54,7 +54,7 @@
 //! iterator over the argument. Each time a "next argument" specifier is seen,
 //! the iterator advances. This leads to behavior like this:
 //!
-//! ```rust
+//! ```
 //! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2"
 //! ```
 //!
@@ -68,7 +68,7 @@
 //! compile-time error. You may refer to the same argument more than once in the
 //! format string, although it must always be referred to with the same type.
 //!
-//! ### Named parameters
+//! ## Named parameters
 //!
 //! Rust itself does not have a Python-like equivalent of named parameters to a
 //! function, but the `format!` macro is a syntax extension which allows it to
@@ -91,7 +91,7 @@
 //! arguments which have names. Like with positional parameters, it is illegal
 //! to provide named parameters that are unused by the format string.
 //!
-//! ### Argument types
+//! ## Argument types
 //!
 //! Each argument's type is dictated by the format string. It is a requirement
 //! that every argument is only ever referred to by one type. For example, this
@@ -105,18 +105,25 @@
 //! hexadecimal as well as an
 //! octal.
 //!
-//! There are various parameters which do require a particular type, however.
-//! Namely if the syntax `{:.*}` is used, then the number of characters to print
-//! precedes the actual object being formatted, and the number of characters
-//! must have the type `usize`. Although a `usize` can be printed with `{}`, it is
-//! illegal to reference an argument as such. For example this is another
+//! There are various parameters which do require a particular type, however. Namely, the `{:.*}`
+//! syntax, which sets the number of numbers after the decimal in floating-point types:
+//!
+//! ```
+//! let formatted_number = format!("{:.*}", 2, 1.234567);
+//!
+//! assert_eq!("1.23", formatted_number)
+//! ```
+//!
+//! If this syntax is used, then the number of characters to print precedes the actual object being
+//! formatted, and the number of characters must have the type `usize`. Although a `usize` can be
+//! printed with `{}`, it is illegal to reference an argument as such. For example this is another
 //! invalid format string:
 //!
 //! ```text
 //! {:.*} {0}
 //! ```
 //!
-//! ### Formatting traits
+//! ## Formatting traits
 //!
 //! When requesting that an argument be formatted with a particular type, you
 //! are actually requesting that an argument ascribes to a particular trait.
@@ -142,7 +149,7 @@
 //! When implementing a format trait for your own type, you will have to
 //! implement a method of the signature:
 //!
-//! ```rust
+//! ```
 //! # use std::fmt;
 //! # struct Foo; // our custom type
 //! # impl fmt::Display for Foo {
@@ -166,7 +173,7 @@
 //! An example of implementing the formatting traits would look
 //! like:
 //!
-//! ```rust
+//! ```
 //! use std::fmt;
 //! use std::f64;
 //! use std::num::Float;
@@ -211,7 +218,7 @@
 //! }
 //! ```
 //!
-//! #### fmt::Display vs fmt::Debug
+//! ### fmt::Display vs fmt::Debug
 //!
 //! These two formatting traits have distinct purposes:
 //!
@@ -231,7 +238,7 @@
 //! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");
 //! ```
 //!
-//! ### Related macros
+//! ## Related macros
 //!
 //! There are a number of related macros in the `format!` family. The ones that
 //! are currently implemented are:
@@ -245,32 +252,33 @@
 //! format_args! // described below.
 //! ```
 //!
-//! #### `write!`
+//! ### `write!`
 //!
 //! This and `writeln` are two macros which are used to emit the format string
 //! to a specified stream. This is used to prevent intermediate allocations of
 //! format strings and instead directly write the output. Under the hood, this
 //! function is actually invoking the `write` function defined in this module.
 //! Example usage is:
 //!
-//! ```rust
+//! ```
 //! # #![allow(unused_must_use)]
 //! let mut w = Vec::new();
 //! write!(&mut w, "Hello {}!", "world");
 //! ```
 //!
-//! #### `print!`
+//! ### `print!`
 //!
 //! This and `println` emit their output to stdout. Similarly to the `write!`
 //! macro, the goal of these macros is to avoid intermediate allocations when
 //! printing output. Example usage is:
 //!
-//! ```rust
+//! ```
 //! print!("Hello {}!", "world");
 //! println!("I have a newline {}", "character at the end");
 //! ```
 //!
-//! #### `format_args!`
+//! ### `format_args!`
+//!
 //! This is a curious macro which is used to safely pass around
 //! an opaque object describing the format string. This object
 //! does not require any heap allocations to create, and it only
@@ -303,7 +311,7 @@
 //! it would internally pass around this structure until it has been determined
 //! where output should go to.
 //!
-//! ## Syntax
+//! # Syntax
 //!
 //! The syntax for the formatting language used is drawn from other languages,
 //! so it should not be too alien. Arguments are formatted with python-like
@@ -326,14 +334,14 @@
 //! parameter := integer '$'
 //! ```
 //!
-//! ## Formatting Parameters
+//! # Formatting Parameters
 //!
 //! Each argument being formatted can be transformed by a number of formatting
 //! parameters (corresponding to `format_spec` in the syntax above). These
 //! parameters affect the string representation of what's being formatted. This
 //! syntax draws heavily from Python's, so it may seem a bit familiar.
 //!
-//! ### Fill/Alignment
+//! ## Fill/Alignment
 //!
 //! The fill character is provided normally in conjunction with the `width`
 //! parameter. This indicates that if the value being formatted is smaller than
@@ -345,7 +353,7 @@
 //! * `^` - the argument is center-aligned in `width` columns
 //! * `>` - the argument is right-aligned in `width` columns
 //!
-//! ### Sign/#/0
+//! ## Sign/#/0
 //!
 //! These can all be interpreted as flags for a particular formatter.
 //!
@@ -368,7 +376,7 @@
 //!         same format would yield `-0000001` for the integer `-1`. Notice that
 //!         the negative version has one fewer zero than the positive version.
 //!
-//! ### Width
+//! ## Width
 //!
 //! This is a parameter for the "minimum width" that the format should take up.
 //! If the value's string does not fill up this many characters, then the
@@ -384,7 +392,7 @@
 //! parameters by using the `2$` syntax indicating that the second argument is a
 //! `usize` specifying the width.
 //!
-//! ### Precision
+//! ## Precision
 //!
 //! For non-numeric types, this can be considered a "maximum width". If the
 //! resulting string is longer than this width, then it is truncated down to
@@ -395,7 +403,7 @@
 //! For floating-point types, this indicates how many digits after the decimal
 //! point should be printed.
 //!
-//! ## Escaping
+//! # Escaping
 //!
 //! The literal characters `{` and `}` may be included in a string by preceding
 //! them with the same character. For example, the `{` character is escaped with