Edit comments for websocket, drop hashcode() from interface.

sdk/lib/io/websocket.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * Web socket status codes used when closing a web socket connection.
  */
 abstract class WebSocketStatus {
   static const int NORMAL_CLOSURE = 1000;
   static const int GOING_AWAY = 1001;
   static const int PROTOCOL_ERROR = 1002;
   static const int UNSUPPORTED_DATA = 1003;
   static const int RESERVED_1004  = 1004;
   static const int NO_STATUS_RECEIVED = 1005;
   static const int ABNORMAL_CLOSURE = 1006;
   static const int INVALID_FRAME_PAYLOAD_DATA = 1007;
   static const int POLICY_VIOLATION = 1008;
   static const int MESSAGE_TOO_BIG = 1009;
   static const int MISSING_MANDATORY_EXTENSION = 1010;
   static const int INTERNAL_SERVER_ERROR = 1011;
   static const int RESERVED_1015 = 1015;
 }
 
 /**
- * The web socket protocol is implemented by a HTTP server handler
+ * The web socket protocol is implemented by a HTTP or HTTPS server handler
  * which can be instantiated like this:
  *
  *     WebSocketHandler wsHandler = new WebSocketHandler();
  *
  * and then its onRequest method can be assigned to the HTTP server, e.g.
  *
  *     server.defaultHandler = wsHandler.onRequest;
  *
  * or
  *
@@ skipping 16 matching lines @@
    */
   void set onOpen(callback(WebSocketConnection connection));
 }
 
 
 /**
  * Server web socket connection.
  */
 abstract class WebSocketConnection {
   /**
-   * Sets the callback to be called when a message have been
+   * Sets the callback to be called when a message has been
    * received. The type on [message] is either [:String:] or
    * [:List<int>:] depending on whether it is a text or binary
    * message. If the message is empty [message] will be [:null:].
+   * If [message] is a [:List<int>:] then it will contain byte values
+   * from 0 to 255.
    */
   void set onMessage(void callback(message));
 
   /**
    * Sets the callback to be called when the web socket connection is
    * closed. [status] indicate the reason for closing. For network
    * errors the value of [status] will be
-   * WebSocketStatus.ABNORMAL_CLOSURE]. In this callbach it is
+   * WebSocketStatus.ABNORMAL_CLOSURE]. In this callback it is
    * possible to call [close] if [close] has not already been called.
    * If [close] has still not been called after the close callback
    * returns the received close status will automatically be echoed
    * back to the other end to finish the close handshake.
    */
   void set onClosed(void callback(int status, String reason));
 
   /**
-   * Sends a message. The [message] must be a [:String:] a
-   * [:List<int>:] or [:null:].
+   * Sends a message. The [message] must be a [:String:], a
+   * [:List<int>:] containing bytes, or [:null:].
    */
   send(Object message);
 
   /**
    * Close the web socket connection. The default value for [status]
    * and [reason] are [:null:].
    */
   close([int status, String reason]);
-
-  /**
-   * WebSocketConnection is hashable.
-   */
-  int get hashCode;
 }
 
 
 /**
  * Client web socket connection.
  */
 abstract class WebSocketClientConnection {
   /**
-   * Creates a new web socket client connection based on a HTTP client
-   * connection. The HTTP client connection must be freshly opened.
+   * Creates a new web socket client connection based on a HTTP(S) client
+   * connection. The HTTP or HTTPS client connection must be freshly opened.
    */
   factory WebSocketClientConnection(HttpClientConnection conn,
                                     [List<String> protocols]) {
     return new _WebSocketClientConnection(conn, protocols);
   }
 
   /**
    * Sets the callback to be called when the request object for the
    * opening handshake request is ready. This callback can be used if
-   * one need to add additional headers to the opening handshake
+   * one needs to add additional headers to the opening handshake
    * request.
    */
   void set onRequest(void callback(HttpClientRequest request));
 
   /**
    * Sets the callback to be called when a web socket connection has
    * been established.
    */
   void set onOpen(void callback());
 
   /**
-   * Sets the callback to be called when a message have been
+   * Sets the callback to be called when a message has been
    * received. The type of [message] is either [:String:] or
-   * [:List<int>:] depending on whether it is a text or binary
+   * [:List<int>:], depending on whether it is a text or binary
    * message. If the message is empty [message] will be [:null:].
+   * If the message is a [:List<int>:] then it will contain byte values
+   * from 0 to 255.
    */
   void set onMessage(void callback(message));
 
   /**
    * Sets the callback to be called when the web socket connection is
-   * closed. [status] indicate the reason for closing. For network
+   * closed. [status] indicates the reason for closing. For network
    * errors the value of [status] will be
    * WebSocketStatus.ABNORMAL_CLOSURE].
    */
   void set onClosed(void callback(int status, String reason));
 
   /**
    * Sets the callback to be called when the response object for the
    * opening handshake did not cause a web socket connection
    * upgrade. This will be called in case the response status code is
-   * not 101 (Switching Protocols). If this callback is not set the
-   * [:onError:] callback will be called if the server did not upgrade
-   * the connection.
+   * not 101 (Switching Protocols). If this callback is not set and the
+   * server does not upgrade the connection, the [:onError:] callback will
+   * be called.
    */
   void set onNoUpgrade(void callback(HttpClientResponse response));
 
   /**
    * Sends a message. The [message] must be a [:String:] or a
-   * [:List<int>:]. To send an empty message use either an empty
-   * [:String:] or an empty [:List<int>:]. [:null:] cannot be used.
+   * [:List<int>:] containing bytes. To send an empty message send either
+   * an empty [:String:] or an empty [:List<int>:]. [:null:] cannot be sent.
    */
   send(message);
 
   /**
    * Close the web socket connection. The default value for [status]
    * and [reason] are [:null:].
    */
   close([int status, String reason]);
-
-  /**
-   * WebSocketClientConnection is hashable.
-   */
-  int get hashCode;
 }
 
 
 /**
  * Base class for the events generated by the W3C complient browser
  * API for web sockets.
  */
 abstract class Event { }
 
 /**
  * Event delivered when there is data on a web socket connection.
  */
 abstract class MessageEvent extends Event {
   /**
    * The type of [message] is either [:String:] or [:List<int>:]
    * depending on whether it is a text or binary message. If the
    * message is empty [message] will be [:null:]
+   * If the message is a [:List<int>:] then it will contain byte values
+   * from 0 to 255.
+
    */
   get data;
 }
 
 
 /**
  * Event delivered when a web socket connection is closed.
  */
 abstract class CloseEvent extends Event {
   /**
@@ skipping 79 matching lines @@
    * value will remain [:null:].
    */
   String get protocol;
 
   /**
    * Closes the web socket connection.
    */
   void close(int code, String reason);
 
   /**
-   * Sets the callback to be called when a message have been
+   * Sets the callback to be called when a message has been
    * received.
    */
   void set onmessage(void callback(MessageEvent event));
 
   /**
    * Sends data on the web socket connection. The data in [data] must
-   * be either a [:String:] or [:List<int>:] holding bytes.
+   * be either a [:String:], or a [:List<int>:] holding bytes.
    */
   void send(data);
 }
 
 
 class WebSocketException implements Exception {
   const WebSocketException([String this.message = ""]);
   String toString() => "WebSocketException: $message";
   final String message;
 }