Expand docs of multi-address behavior of some UDP/TCP APIs.

Fixes #22569.

Author: frewsxcv

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)

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))