Improve documentation.

- Introduce ReadMessage and WriteMessage before NextReader and
  NextWriter in the package comment. It's better to introduce the easy
  methods first.
- Move sections on message of types before the concurrency section.

Author: garyburd

doc.go

@@ -6,9 +6,9 @@
 //
 // Overview
 //
-// The Conn type represents a WebSocket connection.
-//
-// A server application calls the Upgrade function to get a pointer to a Conn:
+// 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:
 //
 //  func handler(w http.ResponseWriter, r *http.Request) {
 //      conn, err := websocket.Upgrade(w, r.Header, nil, 1024, 1024)
@@ -22,64 +22,61 @@
 //      ... Use conn to send and receive messages.
 //  }
 //
-// WebSocket messages are represented by the io.Reader interface when receiving
-// a message and by the io.WriteCloser interface when sending a message. An
-// application receives a message by calling the Conn.NextReader method and
-// reading the returned io.Reader to EOF. An application sends a message by
-// calling the Conn.NextWriter method and writing the message to the returned
-// io.WriteCloser. The application terminates the message by closing the
-// io.WriteCloser.
-//
-// The following example shows how to use the connection NextReader and
-// NextWriter method to echo messages:
+// Call the connection WriteMessage and ReadMessages methods to send and
+// receive messages as a slice of bytes. This snippet of code shows how to echo
+// messages using these methods:
 //
 //  for {
-//      mt, r, err := conn.NextReader()
+//      messageType, p, err := conn.ReadMessage()
 //      if err != nil {
 //          return
 //      }
-//      w, err := conn.NextWriter(mt)
-//      if err != nil {
-//          return err
-//      }
-//      if _, err := io.Copy(w, r); err != nil {
-//          return err
-//      }
-//      if err := w.Close(); err != nil {
+//      if _, err := conn.WriteMessaage(messageType, p); err != nil {
 //          return err
 //      }
 //  }
 //
-// The connection ReadMessage and WriteMessage methods are helpers for reading
-// or writing an entire message in one method call. The following example shows
-// how to echo messages using these connection helper methods:
+// In above snippet of code, p is a []byte and messageType is an int with value
+// websocket.BinaryMessage or websocket.TextMessage.
+//
+// An application can also send and receive messages using the io.WriteCloser
+// and io.Reader interfaces. To send a message, call the connection NextWriter
+// method to get an io.WriteCloser, write the message to the writer and close
+// the writer when done. To receive a message, call the connection NextReader
+// method to get an io.Reader and read until io.EOF is returned. This snippet
+// snippet shows how to echo messages using the NextWriter and NextReader
+// methods:
 //
 //  for {
-//      mt, p, err := conn.ReadMessage()
+//      messageType, r, err := conn.NextReader()
 //      if err != nil {
 //          return
 //      }
-//      if _, err := conn.WriteMessaage(mt, p); err != nil {
+//      w, err := conn.NextWriter(messageType)
+//      if err != nil {
+//          return err
+//      }
+//      if _, err := io.Copy(w, r); err != nil {
+//          return err
+//      }
+//      if err := w.Close(); err != nil {
 //          return err
 //      }
 //  }
 //
-// Concurrency
-//
-// A Conn supports a single concurrent caller to the write methods (NextWriter,
-// SetWriteDeadline, WriteMessage) and a single concurrent caller to the read
-// methods (NextReader, SetReadDeadline, ReadMessage). The Close and
-// WriteControl methods can be called concurrently with all other methods.
-//
 // Data Messages
 //
 // The WebSocket protocol distinguishes between text and binary data messages.
 // Text messages are interpreted as UTF-8 encoded text. The interpretation of
 // binary messages is left to the application.
 //
-// This package uses the same types and methods to work with both types of data
-// messages. It is the application's reponsiblity to ensure that text messages
-// are valid UTF-8 encoded text.
+// This package uses the TextMessage and BinaryMessage integer constants to
+// identify the two data message types. The ReadMessage and NextReader methods
+// return the type of the received message. The messageType argument to the
+// WriteMessage and NextWriter methods specifies the type of a sent message.
+//
+// It is the application's responsibility to ensure that text messages are
+// valid UTF-8 encoded text.
 //
 // Control Messages
 //
@@ -95,4 +92,12 @@
 // Connections handle received close messages by returning an error from the
 // ReadMessage method, the NextReader method or from a call to the data message
 // reader returned from NextReader.
+//
+// Concurrency
+//
+// A Conn supports a single concurrent caller to the write methods (NextWriter,
+// SetWriteDeadline, WriteMessage) and a single concurrent caller to the read
+// methods (NextReader, SetReadDeadline, ReadMessage). The Close and
+// WriteControl methods can be called concurrently with all other methods.
+//
 package websocket

server.go

@@ -33,11 +33,11 @@ func (e HandshakeError) Error() string { return e.message }
 // responsible for selecting a subprotocol that is acceptable to the client and
 // echoing that value back to the client. Use the Subprotocols function to get
 // the list of protocols specified by the client. Use the
-// Sec-Websocket-Protocol response header to echo the selected protocol back
-// to the client.
+// Sec-Websocket-Protocol response header to echo the selected protocol back to
+// the client.
 //
-// Appilcations can set cookies by adding a Set-Cookie header to the
-// response header.
+// Appilcations can set cookies by adding a Set-Cookie header to the response
+// header.
 //
 // If the request is not a valid WebSocket handshake, then Upgrade returns an
 // error of type HandshakeError. Applications should handle this error by