Clean up some style (dart-lang/web_socket_channel#120)
Focus on the cross platform class in the README. From the issues we see
some folks aren't aware of the new `WebSocketChannel.connect`
constructor and get caught up with cross platform issues because they
originally picked single platform imports. The vast majority of use
cases are covered by the main import, so drop the sections on the
platform specific imports altogether.
Update some code samples in doc comments for style.
Remove some unnecessary library statements.
diff --git a/pkgs/web_socket_channel/README.md b/pkgs/web_socket_channel/README.md
index 03aa611..731099f 100644
--- a/pkgs/web_socket_channel/README.md
+++ b/pkgs/web_socket_channel/README.md
@@ -5,7 +5,7 @@
[`WebSocketChannel`][WebSocketChannel] API, a cross-platform implementation of
that API that communicates over an underlying [`StreamChannel`][stream_channel],
[an implementation][IOWebSocketChannel] that wraps `dart:io`'s `WebSocket`
-class, and [a similar implementation][HtmlWebSocketChannel] that wrap's
+class, and [a similar implementation][HtmlWebSocketChannel] that wraps
`dart:html`'s.
[stream_channel]: https://pub.dev/packages/stream_channel
@@ -20,14 +20,14 @@
[status]: https://pub.dev/documentation/web_socket_channel/latest/status/status-library.html
```dart
-import 'package:web_socket_channel/io.dart';
+import 'package:web_socket_channel/web_socket_channel.dart';
import 'package:web_socket_channel/status.dart' as status;
main() async {
- var channel = IOWebSocketChannel.connect("ws://localhost:1234");
+ var channel = IOWebSocketChannel.connect(Uri.parse('ws://localhost:1234'));
channel.stream.listen((message) {
- channel.sink.add("received!");
+ channel.sink.add('received!');
channel.sink.close(status.goingAway);
});
}
@@ -57,71 +57,17 @@
[sink.close]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketSink/close.html
`WebSocketChannel` also works as a cross-platform implementation of the
-WebSocket protocol. Because it can't initiate or handle HTTP requests in a
-cross-platform way, the [`WebSocketChannel()` constructor][new] takes an
-underlying [`StreamChannel`][stream_channel] over which it communicates using
-the WebSocket protocol. It also provides the static [`signKey()`][signKey]
-method to make it easier to implement the [initial WebSocket handshake][]. These
-are used in the [`shelf_web_socket`][shelf_web_socket] package to support
-WebSockets in a cross-platform way.
+WebSocket protocol. The [`WebSocketChannel.connect` constructor][connect]
+connects to a listening server using the appropriate implementation for the
+platform. The [`WebSocketChannel()` constructor][new] takes an underlying
+[`StreamChannel`][stream_channel] over which it communicates using the WebSocket
+protocol. It also provides the static [`signKey()`][signKey] method to make it
+easier to implement the [initial WebSocket handshake][]. These are used in the
+[`shelf_web_socket`][shelf_web_socket] package to support WebSockets in a
+cross-platform way.
-[new]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel-class.html
+[connect]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/WebSocketChannel.connect.html
+[new]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/WebSocketChannel.html
[signKey]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/signKey.html
[initial WebSocket handshake]: https://tools.ietf.org/html/rfc6455#section-4.2.2
[shelf_web_socket]: https://pub.dev/packages/shelf_web_socket
-
-## `IOWebSocketChannel`
-
-The [`IOWebSocketChannel`][IOWebSocketChannel] class wraps
-[`dart:io`'s `WebSocket` class][io.WebSocket]. Because it imports `dart:io`, it
-has its own library, `package:web_socket_channel/io.dart`. This allows the main
-`WebSocketChannel` class to be available on all platforms.
-
-[io.WebSocket]: https://api.dartlang.org/stable/dart-io/WebSocket-class.html
-
-An `IOWebSocketChannel` can be created by passing a `dart:io` WebSocket to
-[its constructor][IOWebSocketChannel]. It's more common to want to connect
-directly to a `ws://` or `wss://` URL, in which case
-[`IOWebSocketChannel.connect()`][IOWebSocketChannel.connect] should be used.
-
-[IOWebSocketChannel.connect]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel.io/IOWebSocketChannel/IOWebSocketChannel.connect.html
-
-```dart
-import 'package:web_socket_channel/io.dart';
-
-main() async {
- var channel = IOWebSocketChannel.connect("ws://localhost:8181");
- channel.sink.add("connected!");
- channel.stream.listen((message) {
- // ...
- });
-}
-```
-
-## `HtmlWebSocketChannel`
-
-The [`HtmlWebSocketChannel`][HtmlWebSocketChannel] class wraps
-[`dart:html`'s `WebSocket` class][html.WebSocket]. Because it imports
-`dart:html`, it has its own library, `package:web_socket_channel/html.dart`.
-This allows the main `WebSocketChannel` class to be available on all platforms.
-
-[html.WebSocket]: https://api.dartlang.org/stable/dart-html/WebSocket-class.html
-
-An `HtmlWebSocketChannel` can be created by passing a `dart:html` WebSocket to
-[its constructor][HtmlWebSocketChannel]. It's more common to want to connect
-directly to a `ws://` or `wss://` URL, in which case
-[`HtmlWebSocketChannel.connect()`][HtmlWebSocketChannel.connect] should be used.
-
-[HtmlWebSocketChannel.connect]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel.html/HtmlWebSocketChannel/HtmlWebSocketChannel.connect.html
-
-```dart
-import 'package:web_socket_channel/html.dart';
-
-main() async {
- var channel = HtmlWebSocketChannel.connect("ws://localhost:8181");
- channel.sink.add("connected!");
- channel.stream.listen((message) {
- // ...
- });
-}
-```
diff --git a/pkgs/web_socket_channel/lib/html.dart b/pkgs/web_socket_channel/lib/html.dart
index db42d5d..2819b63 100644
--- a/pkgs/web_socket_channel/lib/html.dart
+++ b/pkgs/web_socket_channel/lib/html.dart
@@ -2,8 +2,6 @@
// 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.
-library web_socket_channel.html;
-
import 'dart:async';
import 'dart:html';
import 'dart:typed_data';
diff --git a/pkgs/web_socket_channel/lib/io.dart b/pkgs/web_socket_channel/lib/io.dart
index e2a7ce4..e6023d6 100644
--- a/pkgs/web_socket_channel/lib/io.dart
+++ b/pkgs/web_socket_channel/lib/io.dart
@@ -2,8 +2,6 @@
// 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.
-library web_socket_channel.io;
-
import 'dart:async';
import 'dart:io';
diff --git a/pkgs/web_socket_channel/lib/status.dart b/pkgs/web_socket_channel/lib/status.dart
index d9cc3a2..121c2cc 100644
--- a/pkgs/web_socket_channel/lib/status.dart
+++ b/pkgs/web_socket_channel/lib/status.dart
@@ -7,11 +7,11 @@
/// This library is intended to be imported with a prefix.
///
/// ```dart
-/// import 'package:web_socket_channel/io.dart';
+/// import 'package:web_socket_channel/web_socket_channel.dart';
/// import 'package:web_socket_channel/status.dart' as status;
///
-/// main() async {
-/// var channel = await IOWebSocketChannel.connect("ws://localhost:1234");
+/// void main() async {
+/// var channel = WebSocketChannel.connect(Uri.parse('ws://localhost:1234'));
/// // ...
/// channel.close(status.goingAway);
/// }
