diff --git a/doc.go b/doc.go
index cb9b349..646c2cf 100644
--- a/doc.go
+++ b/doc.go
@@ -6,14 +6,19 @@
 //
 // Overview
 //
-// The Conn type represents a WebSocket connection. A server application calls
-// the Upgrade function from an HTTP request handler to get a pointer to a
-// Conn:
+// The Conn type represents a WebSocket connection. A server application uses
+// the Upgrade function from an Upgrader object with a HTTP request handler
+// to get a pointer to a Conn:
+//
+//  var upgrader = websocket.Upgrader{
+//      ReadBufferSize:  1024,
+//      WriteBufferSize: 1024,
+//  }
 //
 //  func handler(w http.ResponseWriter, r *http.Request) {
-//      conn, err := websocket.Upgrade(w, r, nil, 1024, 1024)
+//      conn, err := upgrader.Upgrade(w, r, nil)
 //      if _, ok := err.(websocket.HandshakeError); ok {
-//          http.Error(w, "Not a websocket handshake", 400)
+//          ... an error message already has been sent.
 //          return
 //      } else if err != nil {
 //          log.Println(err)
diff --git a/server.go b/server.go
index fb25f2e..f061c61 100644
--- a/server.go
+++ b/server.go
@@ -191,8 +191,6 @@ func (u *Upgrader) Upgrade(w http.ResponseWriter, r *http.Request, responseHeade
 	return c, nil
 }
 
-// This method is deprecated, use websocket.Upgrader instead.
-//
 // Upgrade upgrades the HTTP server connection to the WebSocket protocol.
 //
 // The application is responsible for checking the request origin before
@@ -220,6 +218,8 @@ func (u *Upgrader) Upgrade(w http.ResponseWriter, r *http.Request, responseHeade
 // If the request is not a valid WebSocket handshake, then Upgrade returns an
 // error of type HandshakeError. Applications should handle this error by
 // replying to the client with an HTTP error response.
+//
+// This method is deprecated, use websocket.Upgrader instead.
 func Upgrade(w http.ResponseWriter, r *http.Request, responseHeader http.Header, readBufSize, writeBufSize int) (*Conn, error) {
 	u := Upgrader{ReadBufferSize: readBufSize, WriteBufferSize: writeBufSize}
 	u.Error = func(w http.ResponseWriter, r *http.Request, status int, reason error) {