Mention `ready` in the docs for `connect` (dart-lang/web_socket_channel#287)
Closes dart-lang/web_socket_channel#280
There can be confusion when there are errors creating the channel
because the only wait to catch them is to include an `await
channel.ready` in the try block. Mention that `ready` can complete as an
error in the case of connection failure.
diff --git a/pkgs/web_socket_channel/CHANGELOG.md b/pkgs/web_socket_channel/CHANGELOG.md
index 131c0a8..de523a5 100644
--- a/pkgs/web_socket_channel/CHANGELOG.md
+++ b/pkgs/web_socket_channel/CHANGELOG.md
@@ -1,8 +1,9 @@
-## 2.4.1
+## 2.4.1-wip
- Update the examples to use `WebSocketChannel.ready` and clarify that
`WebSocketChannel.ready` should be awaited before sending data over the
`WebSocketChannel`.
+- Mention `ready` in the docs for `connect`.
## 2.4.0
diff --git a/pkgs/web_socket_channel/lib/src/channel.dart b/pkgs/web_socket_channel/lib/src/channel.dart
index 8f40d75..46d16b8 100644
--- a/pkgs/web_socket_channel/lib/src/channel.dart
+++ b/pkgs/web_socket_channel/lib/src/channel.dart
@@ -134,6 +134,12 @@
/// communicate over the resulting socket.
///
/// The optional [protocols] parameter is the same as `WebSocket.connect`.
+ ///
+ /// A WebSocketChannel is returned synchronously, however the connection is
+ /// not established synchronously.
+ /// The [ready] future will complete after the channel is connected.
+ /// If there are errors creating the connection the [ready] future will
+ /// complete with an error.
factory WebSocketChannel.connect(Uri uri, {Iterable<String>? protocols}) =>
platform.connect(uri, protocols: protocols);
}
diff --git a/pkgs/web_socket_channel/pubspec.yaml b/pkgs/web_socket_channel/pubspec.yaml
index 79be718..1403492 100644
--- a/pkgs/web_socket_channel/pubspec.yaml
+++ b/pkgs/web_socket_channel/pubspec.yaml
@@ -1,5 +1,5 @@
name: web_socket_channel
-version: 2.4.1
+version: 2.4.1-wip
description: >-
StreamChannel wrappers for WebSockets. Provides a cross-platform
