Auto merge of #44233 - Mark-Simulacrum:rollup, r=Mark-Simulacrum

Rollup of 10 pull requests

- Successful merges: #44192, #44199, #44202, #44203, #44205, #44207, #44209, #44223, #44230, #44231
- Failed merges:

3 files changed, 93 insertions, 7 deletions

diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs
index 9ef19cd64b3..e1d7a2531b6 100644
--- a/src/libstd/net/addr.rs
+++ b/src/libstd/net/addr.rs
@@ -767,7 +767,7 @@ impl hash::Hash for SocketAddrV6 {
 ///
 /// let stream = TcpStream::connect(("127.0.0.1", 443));
 /// // or
-/// let stream = TcpStream::connect("127.0.0.1.443");
+/// let stream = TcpStream::connect("127.0.0.1:443");
 /// // or
 /// let stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 443));
 /// ```
diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs
index 2eabb46441b..5467eff202b 100644
--- a/src/libstd/net/tcp.rs
+++ b/src/libstd/net/tcp.rs
@@ -111,15 +111,18 @@ impl TcpStream {
     /// `addr` is an address of the remote host. Anything which implements
     /// [`ToSocketAddrs`] trait can be supplied for the address; see this trait
     /// documentation for concrete examples.
-    /// In case [`ToSocketAddrs::to_socket_addrs()`] returns more than one entry,
-    /// then the first valid and reachable address is used.
+    ///
+    /// If `addr` yields multiple addresses, `connect` will be attempted with
+    /// each of the addresses until a connection is successful. If none of
+    /// the addresses result in a successful connection, the error returned from
+    /// the last connection attempt (the last address) is returned.
     ///
     /// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
-    /// [`ToSocketAddrs::to_socket_addrs()`]:
-    /// ../../std/net/trait.ToSocketAddrs.html#tymethod.to_socket_addrs
     ///
     /// # Examples
     ///
+    /// Open a TCP connection to `127.0.0.1:8080`:
+    ///
     /// ```no_run
     /// use std::net::TcpStream;
     ///
@@ -129,6 +132,23 @@ impl TcpStream {
     ///     println!("Couldn't connect to server...");
     /// }
     /// ```
+    ///
+    /// Open a TCP connection to `127.0.0.1:8080`. If the connection fails, open
+    /// a TCP connection to `127.0.0.1:8081`:
+    ///
+    /// ```no_run
+    /// use std::net::{SocketAddr, TcpStream};
+    ///
+    /// let addrs = [
+    ///     SocketAddr::from(([127, 0, 0, 1], 8080)),
+    ///     SocketAddr::from(([127, 0, 0, 1], 8081)),
+    /// ];
+    /// if let Ok(stream) = TcpStream::connect(&addrs[..]) {
+    ///     println!("Connected to the server!");
+    /// } else {
+    ///     println!("Couldn't connect to server...");
+    /// }
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn connect<A: ToSocketAddrs>(addr: A) -> io::Result<TcpStream> {
         super::each_addr(addr, net_imp::TcpStream::connect).map(TcpStream)
@@ -557,16 +577,36 @@ impl TcpListener {
     /// The address type can be any implementor of [`ToSocketAddrs`] trait. See
     /// its documentation for concrete examples.
     ///
+    /// If `addr` yields multiple addresses, `bind` will be attempted with
+    /// each of the addresses until one succeeds and returns the listener. If
+    /// none of the addresses succeed in creating a listener, the error returned
+    /// from the last attempt (the last address) is returned.
+    ///
     /// [`local_addr`]: #method.local_addr
     /// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
     ///
     /// # Examples
     ///
+    /// Create a TCP listener bound to `127.0.0.1:80`:
+    ///
     /// ```no_run
     /// use std::net::TcpListener;
     ///
     /// let listener = TcpListener::bind("127.0.0.1:80").unwrap();
     /// ```
+    ///
+    /// Create a TCP listener bound to `127.0.0.1:80`. If that fails, create a
+    /// TCP listener bound to `127.0.0.1:443`:
+    ///
+    /// ```no_run
+    /// use std::net::{SocketAddr, TcpListener};
+    ///
+    /// let addrs = [
+    ///     SocketAddr::from(([127, 0, 0, 1], 80)),
+    ///     SocketAddr::from(([127, 0, 0, 1], 443)),
+    /// ];
+    /// let listener = TcpListener::bind(&addrs[..]).unwrap();
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<TcpListener> {
         super::each_addr(addr, net_imp::TcpListener::bind).map(TcpListener)
diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs
index 9aff9897885..35001833383 100644
--- a/src/libstd/net/udp.rs
+++ b/src/libstd/net/udp.rs
@@ -69,14 +69,34 @@ impl UdpSocket {
     /// The address type can be any implementor of [`ToSocketAddrs`] trait. See
     /// its documentation for concrete examples.
     ///
+    /// If `addr` yields multiple addresses, `bind` will be attempted with
+    /// each of the addresses until one succeeds and returns the socket. If none
+    /// of the addresses succeed in creating a socket, the error returned from
+    /// the last attempt (the last address) is returned.
+    ///
     /// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
     ///
     /// # Examples
     ///
+    /// Create a UDP socket bound to `127.0.0.1:3400`:
+    ///
     /// ```no_run
     /// use std::net::UdpSocket;
     ///
-    /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
+    /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address");
+    /// ```
+    ///
+    /// Create a UDP socket bound to `127.0.0.1:3400`. If the socket cannot be
+    /// bound to that address, create a UDP socket bound to `127.0.0.1:3401`:
+    ///
+    /// ```no_run
+    /// use std::net::{SocketAddr, UdpSocket};
+    ///
+    /// let addrs = [
+    ///     SocketAddr::from(([127, 0, 0, 1], 3400)),
+    ///     SocketAddr::from(([127, 0, 0, 1], 3401)),
+    /// ];
+    /// let socket = UdpSocket::bind(&addrs[..]).expect("couldn't bind to address");
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<UdpSocket> {
@@ -130,6 +150,9 @@ impl UdpSocket {
     /// Address type can be any implementor of [`ToSocketAddrs`] trait. See its
     /// documentation for concrete examples.
     ///
+    /// It is possible for `addr` to yield multiple addresses, but `send_to`
+    /// will only send data to the first address yielded by `addr`.
+    ///
     /// This will return an error when the IP version of the local socket
     /// does not match that returned from [`ToSocketAddrs`].
     ///
@@ -562,14 +585,37 @@ impl UdpSocket {
     /// `recv` syscalls to be used to send data and also applies filters to only
     /// receive data from the specified address.
     ///
+    /// If `addr` yields multiple addresses, `connect` will be attempted with
+    /// each of the addresses until a connection is successful. If none of
+    /// the addresses are able to be connected, the error returned from the
+    /// last connection attempt (the last address) is returned.
+    ///
     /// # Examples
     ///
+    /// Create a UDP socket bound to `127.0.0.1:3400` and connect the socket to
+    /// `127.0.0.1:8080`:
+    ///
     /// ```no_run
     /// use std::net::UdpSocket;
     ///
-    /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
+    /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address");
     /// socket.connect("127.0.0.1:8080").expect("connect function failed");
     /// ```
+    ///
+    /// Create a UDP socket bound to `127.0.0.1:3400` and connect the socket to
+    /// `127.0.0.1:8080`. If that connection fails, then the UDP socket will
+    /// connect to `127.0.0.1:8081`:
+    ///
+    /// ```no_run
+    /// use std::net::{SocketAddr, UdpSocket};
+    ///
+    /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address");
+    /// let connect_addrs = [
+    ///     SocketAddr::from(([127, 0, 0, 1], 8080)),
+    ///     SocketAddr::from(([127, 0, 0, 1], 8081)),
+    /// ];
+    /// socket.connect(&connect_addrs[..]).expect("connect function failed");
+    /// ```
     #[stable(feature = "net2_mutators", since = "1.9.0")]
     pub fn connect<A: ToSocketAddrs>(&self, addr: A) -> io::Result<()> {
         super::each_addr(addr, |addr| self.0.connect(addr))