Allow additional headers for WebSocket connect

sdk/lib/io/websocket.dart

Index: sdk/lib/io/websocket.dart
diff --git a/sdk/lib/io/websocket.dart b/sdk/lib/io/websocket.dart
index 327ef3aafff218300dd82a20dcf20ac8326d8305..225c9cea4981e834a83c1b6308368b4e952f78b9 100644
--- a/sdk/lib/io/websocket.dart
+++ b/sdk/lib/io/websocket.dart
@@ -126,12 +126,26 @@ abstract class WebSocket implements Stream, StreamSink {
 
   /**
    * Create a new web socket connection. The URL supplied in [url]

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

I think "web socket" is usually written "WebSocket". 
Probably change it everywhere.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

-   * must use the scheme [:ws:] or [:wss:]. The [protocols] argument is
-   * specifying the subprotocols the client is willing to speak.
+   * must use the scheme `ws` or `wss`.
+   *
+   * The [protocols] argument is specifying the subprotocols the
+   * client is willing to speak.
+   *
+   * The [headers] argument is specifying additional HTTP headers for
+   * the initial upgrade request. This would typically be the `Origin`
+   * header and potentially cookies. The key of the map are the header

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

The key -> The keys.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

+   * fields and the values are either String or List<String>.

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

What is an "upgrade request"? Either say something about the underlying protocol
or link to an external description.

[Søren Gjesse, 2015/01/14 13:54:26]

Changed

the initial upgrade request

to

setting up the connection

+   *
+   * Even if [headers] is provided, there are a number of headers

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

Drop the "even" part. Just go directly to the facts.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

+   * which are controlled by the web socket connection process. These
+   * headers are: `connection`, `sec-websocket-version`,
+   * `sec-websocket-key`, `upgrade` and `sec-websocket-protocol`. If

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

Put the headers in alphabetical order. It looks random now.
Maybe make it a bullet list?

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

+   * any of these are passed in the `headers` they will be ignored.

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

add "map" after `headers`. Just "the headers" doesn't sound right.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

    */
   static Future<WebSocket> connect(String url,
-                                   {List<String> protocols: const []}) =>
-      _WebSocketImpl.connect(url, protocols);
+                                   {Iterable<String> protocols: const [],

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

I'd use "null" as default, and then do the dispatch inside the function. No need
to put the "const []" into the API documentation.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

+                                    Map<String, dynamic> headers}) =>
+      _WebSocketImpl.connect(url, protocols, headers);
 
   @Deprecated('This constructor will be removed in Dart 2.0. Use `implements`'
       ' instead of `extends` if implementing this abstract class.')