Auto merge of #49642 - kennytm:rollup, r=kennytm

Rollup of 25 pull requests

Successful merges:

 - #49179 (Handle future deprecation annotations )
 - #49512 (Add support for variant and types fields for intra links)
 - #49515 (fix targetted value background)
 - #49516 (Add missing anchor for union type fields)
 - #49532 (Add test for rustdoc ignore test)
 - #49533 (Add #[must_use] to a few standard library methods)
 - #49540 (Fix miri Discriminant() for non-ADT)
 - #49559 (Introduce Vec::resize_with method (see #41758))
 - #49570 (avoid IdxSets containing garbage above the universe length)
 - #49577 (Stabilize String::replace_range)
 - #49599 (Fix typo)
 - #49603 (Fix url for intra link provided method)
 - #49607 (Stabilize iterator methods in 1.27)
 - #49609 (run-pass/attr-stmt-expr: expand test cases)
 - #49612 (Fix "since" version for getpid feature.)
 - #49618 (Fix build error when compiling libcore for 16bit targets)
 - #49619 (tweak core::fmt docs)
 - #49637 (Stabilize parent_id())
 - #49639 (Update Cargo)
 - #49628 (Re-write the documentation index)
 - #49594 (Add some performance guidance to std::fs and std::io docs)
 - #49625 (miri: add public alloc_kind accessor)
 - #49634 (Add a test for the fix to issue #43058)
 - #49641 (Regression test for #46314)
 - #49547 (Unignore borrowck test)

Failed merges:

6 files changed, 33 insertions, 7 deletions

diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index 479e4d08f4b..7bd1adc411a 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -231,7 +231,9 @@ fn initial_buffer_size(file: &File) -> usize {
 /// Read the entire contents of a file into a bytes vector.
 ///
 /// This is a convenience function for using [`File::open`] and [`read_to_end`]
-/// with fewer imports and without an intermediate variable.
+/// with fewer imports and without an intermediate variable.  It pre-allocates a
+/// buffer based on the file size when available, so it is generally faster than
+/// reading into a vector created with `Vec::new()`.
 ///
 /// [`File::open`]: struct.File.html#method.open
 /// [`read_to_end`]: ../io/trait.Read.html#method.read_to_end
@@ -270,7 +272,9 @@ pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> {
 /// Read the entire contents of a file into a string.
 ///
 /// This is a convenience function for using [`File::open`] and [`read_to_string`]
-/// with fewer imports and without an intermediate variable.
+/// with fewer imports and without an intermediate variable.  It pre-allocates a
+/// buffer based on the file size when available, so it is generally faster than
+/// reading into a string created with `String::new()`.
 ///
 /// [`File::open`]: struct.File.html#method.open
 /// [`read_to_string`]: ../io/trait.Read.html#method.read_to_string
diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs
index cefff2f143c..d6eac748334 100644
--- a/src/libstd/io/buffered.rs
+++ b/src/libstd/io/buffered.rs
@@ -25,6 +25,12 @@ use memchr;
 /// results in a system call. A `BufReader` performs large, infrequent reads on
 /// the underlying [`Read`] and maintains an in-memory buffer of the results.
 ///
+/// `BufReader` can improve the speed of programs that make *small* and
+/// *repeated* read calls to the same file or network socket.  It does not
+/// help when reading very large amounts at once, or reading just one or a few
+/// times.  It also provides no advantage when reading from a source that is
+/// already in memory, like a `Vec<u8>`.
+///
 /// [`Read`]: ../../std/io/trait.Read.html
 /// [`TcpStream::read`]: ../../std/net/struct.TcpStream.html#method.read
 /// [`TcpStream`]: ../../std/net/struct.TcpStream.html
@@ -180,7 +186,7 @@ impl<R: Read> BufReader<R> {
     ///
     /// # Examples
     ///
-    /// ```no_ru
+    /// ```no_run
     /// # #![feature(bufreader_buffer)]
     /// use std::io::{BufReader, BufRead};
     /// use std::fs::File;
@@ -359,6 +365,12 @@ impl<R: Seek> Seek for BufReader<R> {
 /// `BufWriter` keeps an in-memory buffer of data and writes it to an underlying
 /// writer in large, infrequent batches.
 ///
+/// `BufWriter` can improve the speed of programs that make *small* and
+/// *repeated* write calls to the same file or network socket.  It does not
+/// help when writing very large amounts at once, or writing just one or a few
+/// times.  It also provides no advantage when writing to a destination that is
+/// in memory, like a `Vec<u8>`.
+///
 /// When the `BufWriter` is dropped, the contents of its buffer will be written
 /// out. However, any errors that happen in the process of flushing the buffer
 /// when the writer is dropped will be ignored. Code that wishes to handle such
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 63b631ace96..3b8c42ddb39 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -595,6 +595,11 @@ pub trait Read {
     ///     Ok(())
     /// }
     /// ```
+    ///
+    /// (See also the [`std::fs::read`] convenience function for reading from a
+    /// file.)
+    ///
+    /// [`std::fs::read`]: ../fs/fn.read.html
     #[stable(feature = "rust1", since = "1.0.0")]
     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
         read_to_end(self, buf)
@@ -633,6 +638,11 @@ pub trait Read {
     ///     Ok(())
     /// }
     /// ```
+    ///
+    /// (See also the [`std::fs::read_to_string`] convenience function for
+    /// reading from a file.)
+    ///
+    /// [`std::fs::read_to_string`]: ../fs/fn.read_to_string.html
     #[stable(feature = "rust1", since = "1.0.0")]
     fn read_to_string(&mut self, buf: &mut String) -> Result<usize> {
         // Note that we do *not* call `.read_to_end()` here. We are passing
diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs
index 47609f17221..5ef7c159655 100644
--- a/src/libstd/macros.rs
+++ b/src/libstd/macros.rs
@@ -341,8 +341,8 @@ pub mod builtin {
     /// format string in `format_args!`.
     ///
     /// ```rust
-    /// let display = format!("{:?}", format_args!("{} foo {:?}", 1, 2));
-    /// let debug = format!("{}", format_args!("{} foo {:?}", 1, 2));
+    /// let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2));
+    /// let display = format!("{}", format_args!("{} foo {:?}", 1, 2));
     /// assert_eq!("1 foo 2", display);
     /// assert_eq!(display, debug);
     /// ```
diff --git a/src/libstd/process.rs b/src/libstd/process.rs
index b463a6d88fe..40bc84f4bc1 100644
--- a/src/libstd/process.rs
+++ b/src/libstd/process.rs
@@ -1426,7 +1426,7 @@ pub fn abort() -> ! {
 /// ```
 ///
 ///
-#[stable(feature = "getpid", since = "1.27.0")]
+#[stable(feature = "getpid", since = "1.26.0")]
 pub fn id() -> u32 {
     ::sys::os::getpid()
 }
diff --git a/src/libstd/sys/unix/ext/process.rs b/src/libstd/sys/unix/ext/process.rs
index 60309bec6d4..7b4ec20d91f 100644
--- a/src/libstd/sys/unix/ext/process.rs
+++ b/src/libstd/sys/unix/ext/process.rs
@@ -193,7 +193,7 @@ impl IntoRawFd for process::ChildStderr {
 }
 
 /// Returns the OS-assigned process identifier associated with this process's parent.
-#[unstable(feature = "unix_ppid", issue = "46104")]
+#[stable(feature = "unix_ppid", since = "1.27.0")]
 pub fn parent_id() -> u32 {
     ::sys::os::getppid()
 }