net: document that Header.Get key is case insensitive

Document that key in Header.Get(key) is case insensitive in
http.Header, mail.Header, textproto.Header.

Fixes golang#18019

Change-Id: Iba7932491e02e555190b6fce053088b580a853ef
Reviewed-on: https://go-review.googlesource.com/33530
Reviewed-by: Brad Fitzpatrick <[email protected]>

src/net/http/header.go

@@ -32,9 +32,11 @@ func (h Header) Set(key, value string) {
 }
 
 // Get gets the first value associated with the given key.
+// It is case insensitive; textproto.CanonicalMIMEHeaderKey is used
+// to canonicalize the provided key.
 // If there are no values associated with the key, Get returns "".
-// To access multiple values of a key, access the map directly
-// with CanonicalHeaderKey.
+// To access multiple values of a key, or to use non-canonical keys,
+// access the map directly.
 func (h Header) Get(key string) string {
 	return textproto.MIMEHeader(h).Get(key)
 }

src/net/mail/message.go

@@ -107,7 +107,11 @@ func ParseDate(date string) (time.Time, error) {
 type Header map[string][]string
 
 // Get gets the first value associated with the given key.
+// It is case insensitive; CanonicalMIMEHeaderKey is used
+// to canonicalize the provided key.
 // If there are no values associated with the key, Get returns "".
+// To access multiple values of a key, or to use non-canonical keys,
+// access the map directly.
 func (h Header) Get(key string) string {
 	return textproto.MIMEHeader(h).Get(key)
 }

src/net/textproto/header.go

@@ -23,8 +23,10 @@ func (h MIMEHeader) Set(key, value string) {
 }
 
 // Get gets the first value associated with the given key.
+// It is case insensitive; CanonicalMIMEHeaderKey is used
+// to canonicalize the provided key.
 // If there are no values associated with the key, Get returns "".
-// Get is a convenience method. For more complex queries,
+// To access multiple values of a key, or to use non-canonical keys,
 // access the map directly.
 func (h MIMEHeader) Get(key string) string {
 	if h == nil {