net/http: document how Request.Cookie deals with duplicate cookies

RFC 6265, section 4.2.2 says:
<<<
Although cookies are serialized linearly in the Cookie header,
servers SHOULD NOT rely upon the serialization order.  In particular,
if the Cookie header contains two cookies with the same name (e.g.,
that were set with different Path or Domain attributes), servers
SHOULD NOT rely upon the order in which these cookies appear in the
header.
>>>

This statement seems to indicate that cookies should conceptually
be thought of as a map of keys to sets of values (map[key][]value).
However, in practice, everyone pretty much treats cookies as a
map[key]value and the API for Request.Cookie seems to indicate that.

We should update the documentation for Request.Cookie to warn the
user what happens when there is are multiple cookies with the same
key. I deliberately did not want to say *which* cookie is returned.

Change-Id: Id3e0e24b2b14ca2d9ea8b13f82ba739edaa71cf0
Reviewed-on: https://go-review.googlesource.com/29364Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/net/http/request.go

@@ -329,6 +329,8 @@ var ErrNoCookie = errors.New("http: named cookie not present")
 
 // Cookie returns the named cookie provided in the request or
 // ErrNoCookie if not found.
+// If multiple cookies match the given name, only one cookie will
+// be returned.
 func (r *Request) Cookie(name string) (*Cookie, error) {
 	for _, c := range readCookies(r.Header, name) {
 		return c, nil