implementing (some of) @garyburd's suggestions

doc.go

@@ -6,9 +6,8 @@
 //
 // Overview
 //
-// The Conn type represents a WebSocket connection. Within the context of an
+// The Conn type represents a WebSocket connection. A server application calls
-// HTTP request handler, a server application calls the Upgrade method of an
+// the Upgrader.Upgrade method from an HTTP request handler to get a *Conn:
-// Upgrader instance obtaining a pointer to a Conn:
 //
 //  var upgrader = websocket.Upgrader{
 //      ReadBufferSize:  1024,
@@ -152,10 +151,9 @@
 // origin policy checking using the CheckOrigin field associated with the
 // Upgrader instance.
 //
-// By contrast, the deprecated package-level Upgrade function
+// The deprecated package-level Upgrade function does not perform origin
-// does not perform origin checking. In this case is the application's
+// checking. The application is responsible for checking the Origin header
-// responsibility to manually check the Origin header before calling the
+// before calling the Upgrade function.
-// package-level Upgrade function.
 //
 // Compression EXPERIMENTAL
 //

server.go

@@ -228,14 +228,13 @@ func (u *Upgrader) Upgrade(w http.ResponseWriter, r *http.Request, responseHeade
 	return c, nil
 }
 
-// DEPRECATED - use websocket.Upgrader instead.
+// Deprecated: Use websocket.Upgrader instead.
 //
 // Upgrade upgrades the HTTP server connection to the WebSocket protocol.
 //
-// Note that the application is responsible for checking the request origin
+// Upgrade does not perform origin checking. The application is responsible for
-// before calling Upgrade. This is not done automatically as with the use of the
+// checking the Origin header before calling Upgrade. An example implementation
-// Upgrader.Upgrade method. An example implementation of the same origin policy
+// of the same origin policy check is:
-// check is:
 //
 //	if req.Header.Get("Origin") != "http://"+req.Host {
 //		http.Error(w, "Origin not allowed", 403)