Rollup merge of #33167 - benaryorg:master, r=alexcrichton

clarify documentation of TcpStream::connect() for multiple valid addresses

I am not sure how the UDP part of the stdlib behaves when passing multiple valid addresses, but it should be mentioned as there are legit use cases for [`impl<'a> ToSocketAddrs for &'a [SocketAddr]`](http://doc.rust-lang.org/nightly/std/net/trait.ToSocketAddrs.html), a TCP fallback only being one.

Just a little example program for anyone willing to enhance the documentation further:

```rust
use std::net::SocketAddr;
use std::net::ToSocketAddrs;
use std::net::TcpStream;

fn main()
{
	let v: Vec<SocketAddr> = vec!
	[
		"127.0.0.1:1338".to_socket_addrs().unwrap().next().unwrap(),
		"127.0.0.1:1337".to_socket_addrs().unwrap().next().unwrap(),
		"127.0.0.1:1339".to_socket_addrs().unwrap().next().unwrap(),
	];

	let stream = TcpStream::connect(&v[..]).unwrap();
}
```

1 files changed, 2 insertions, 0 deletions

diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs
index a7738e31700..5ab0d5a0877 100644
--- a/src/libstd/net/tcp.rs
+++ b/src/libstd/net/tcp.rs
@@ -86,6 +86,8 @@ 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.
     #[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)