net: document consecutive dialing in net.Dial

document about the consecutive dialing introduced in Go 1.5.
If address is resolved to multiple addresses,
Dial will try each address in order until one succeeds.
Deadline is used to try each address (calculated based on
total number of resolved addresses)

Fixes: #17617

Change-Id: I56b6399edb640c8ef507675f98e0bd45a50d4e2d
Reviewed-on: https://go-review.googlesource.com/34176Reviewed-by: Ian Lance Taylor <iant@golang.org>

src/net/dial.go

@@ -265,6 +265,9 @@ func (r *Resolver) resolveAddrList(ctx context.Context, op, network, addr string
 //	Dial("ip6:ipv6-icmp", "2001:db8::1")
 //
 // For Unix networks, the address must be a file system path.
+
+// If the host is resolved to multiple addresses,
+// Dial will try each address in order until one succeeds.
 func Dial(network, address string) (Conn, error) {
 	var d Dialer
 	return d.Dial(network, address)
@@ -299,6 +302,12 @@ func (d *Dialer) Dial(network, address string) (Conn, error) {
 // connected, any expiration of the context will not affect the
 // connection.
 //
+// If the host in the address parameter resolves to multiple network addresses,
+// and if a timeout is given, the connection to each address is given an
+// appropriate fraction of the time to connect. For example, if a host has
+// 4 IP addresses and the timeout is 1 minute, the connect to each single
+// address will be given 15 seconds to complete before trying the next one.
+//
 // See func Dial for a description of the network and address
 // parameters.
 func (d *Dialer) DialContext(ctx context.Context, network, address string) (Conn, error) {