Add Dialer comment explaining interaction of net dial functions with proxy

Author: seans3

client.go

@@ -51,6 +51,37 @@ func NewClient(netConn net.Conn, u *url.URL, requestHeader http.Header, readBufS
 //
 // It is safe to call Dialer's methods concurrently.
 type Dialer struct {
+	// Custom dial functions can be set on the Dialer to create the TCP connection
+	// to the backend server. Multiple dial functions can be set simultaneously,
+	// with the priority of the dial function as follows:
+	//   1) NetDialTLSContext (only if backend server scheme is HTTPS)
+	//   2) NetDialContext
+	//   3) NetDial
+	// IMPORTANT CAVEAT: If the "proxy" function field is also set, and it returns
+	// a valid proxy URL, then the custom dial functions INSTEAD create the TCP
+	// connection to the proxy. The matrix of proxy/backend schemes with custom dial
+	// functions looks like:
+	//   1) Proxy: HTTP, Backend: HTTP
+	//     a) NetDialContext, then NetDial functions used to connect to proxy
+	//        if set.
+	//   2) Proxy: HTTP, Backend: HTTPS
+	//     a) NetDialContext, then NetDial functions used for proxy connection
+	//        if set.
+	//     b) TLSClientConfig used for backend server TLS handshake over previously
+	//        created proxy connection. (NetDialTLSContext ignored if set).
+	//   3) Proxy: HTTPS, Backend: HTTP
+	//     a) NetDialTLSContext used to dial/TLS handshake proxy if set.
+	//     b) Otherwise if NetDialContext or NetDial are set, the are used
+	//        to create TCP connection to proxy, while TLSClientConfig is
+	//        used to perform proxy TLS handshake.
+	//   4) Proxy: HTTPS, Backend: HTTPS
+	//     a) NetDialTLSContext used to dial/TLS handshake proxy if set.
+	//     b) Otherwise if NetDialContext or NetDial are set, the are used
+	//        to create TCP connection to proxy, while TLSClientConfig is
+	//        used to perform proxy TLS handshake.
+	//     c) TLSClientConfig is also used for backend server TLS handshake
+	//        over previously created proxy connection.
+	//
 	// NetDial specifies the dial function for creating TCP connections. If
 	// NetDial is nil, net.Dialer DialContext is used.
 	// If "Proxy" field is also set, this function dials the proxy.